Det här avsnittet beskriver Efecte Web API och externa applikationer som används för att integrera sig med Efecte. API är byggt ovanpå standard HTTP-protokollet. Efecte Web API metoder anropas från Efecte URL + /serviceName, där serviceName är namnet på den tjänst vi vill anropa. Till exempel: https://localhost:8080/esm/search.ws eller i Efecte Cloud https://base_url/api/itsm/search.ws .

Innan du använder Web API , vänligen läs kapitlet "Autentisering", som beskriver autentisering till Web API och ger ytterligare information om roller och behörigheter. Detta kapitel behandlar också hur man skapar Web API roller och användare. Web API användaren måste vara ett lokalt ESM-konto, inte ett EIM-konto som används för inloggningar i molnmiljöer.

Det finns vissa operationer som kan vara långsamma att bearbeta. Till exempel tar operationer som importerar referenser med flera värden vanligtvis längre tid jämfört med importer utan referenser. Dessutom kan komplicerade uttryck i mallar ta långsam bearbetning av importer. Du bör alltid filtrera bort resultat med hjälp av where och t.ex. templateCode i search.ws.

DataCardImport-tjänsten

För att skapa ett nytt datakort i Efecte måste användaren anropa dataCardImport-tjänsten. Tjänsten tar datakorts-XML som en HTTP-BODY, så anroparen behöver känna till XML-syntaxen och Efecte-schemat för det skapade datakortet. Detta dokument specificerar inte XML-schemat, så se Efecte XML-schemabeskrivningen för information om det. Parametern createDataCards måste sättas till true när nya datakort skapas.

För att kunna ändra ett befintligt datakort måste du ha minst ett datakortfält i den skickade XML-filen som är definierat som unikt i Efecte. Efecte försöker sedan matcha inkommande data med ett datakort och uppdatera det matchade kortet. Parametern updateDataCards måste sättas till true när befintliga datakort ändras.

Vid uppdatering av datakort ersätter XML-attributvärden de befintliga värdena och de fält som inte finns i XML behålls som de är i Efecte. Om du vill ta bort attributvärden från Efecte, lämna value-elementet i XML-filen tomt och använd parametern removeEmptyValues.
Observera att i integrationssyfte är ett bra sätt att hantera importer att endast importera ett datakort åt gången och hålla trafiken på en rimlig nivå av följande skäl:

• Felkontroll är enklare, på så sätt kan felaktiga enheter från importen identifieras direkt.
• Import av ett stort antal datakort kan orsaka timeouts.

HTTP-parametrar

Här är en lista över möjliga HTTP-parametrar som kan användas (HTTP-parametrar för DataCardImport-tjänsten):

* Antingen mapp-ID eller mappkod måste inkluderas i parametrarna

Fel i DataCardImport

Generellt sett, om någon av de obligatoriska parametrarna (listade i tabell 7) saknas eller innehåller ogiltiga värden, returneras ett Web API fel. Detta är även fallet med Web API autentiserings- och auktoriseringsfel. (Se kapitel 5 Web API fel för mer information om Web API fel.)

Om något annat går fel under importen av vissa datakort (t.ex. om mallen för importerade kort är felkonfigurerad), returnerar DataCardImport-tjänsten innehållande information om hanterade datakort och om eventuella fel som uppstått under importen.

Värden som ska importeras ska finnas inuti <value>-elementet. Om värden importeras inom <reference>-element skapas felaktiga referenser till själva datakortet. Om referenser behövs, se till att webb API användaren har åtkomst till mallen du refererar till, annars skapas ingen referens. Referenserna måste vara riktade mot mallens primära värde.

Exempel på begäran och svar

Begäran

Tjänst: dataCardImport.ws

URL-exempel:
https://localhost:8080/esm/dataCardImport.ws?mappkod=incident_management

Meddelandetext:

<entityset>
 <entity>
     <template code="incident"/>
     <attribute code="subject">
       <value>Test incident</value>
     </attribute>
     <attribute code="category">
       <value>Testing</value>
     </attribute>
     <attribute code="impact">
       <value>3. Low</value>
     </attribute>
     <attribute code="urgency">
       <value>3. Low</value>
     </attribute>
 </entity>  
</entityset>

Svar

<?xml version="1.0" encoding="utf-8"?>
<entity-import-report>
   <start-time>09.07.2018 09:03:04</start-time>
   <total-time>10,494</total-time>
   <entities-handled-per-second>0,095</entities-handled-per-second>
   <average-entity-handling-time>10,494</average-entity-handling-time>
   <user>webapi</user>
   <entities-handled>1</entities-handled>
   <entities-saved>1</entities-saved>
   <entities-updated>0</entities-updated>
   <entities-created>1</entities-created>
</entity-import-report>

Ta bort tjänst

För att ta bort ett befintligt datakort från Efecte måste användaren anropa borttagningstjänsten. Tjänsten kan ta bort datakort baserat på två olika kriterier:

• Internt datakorts-ID (enhets-ID).
• En sökfråga; datakort som matchar frågan kommer att tas bort.

HTTP-parametrar

Ta bort HTTP-parametrar för tjänsten:

* Endera av de två parametrarna (ids, query) krävs. Parametrarna hanteras i denna ordning, och endast en kommer att beaktas vid ett anrop av tjänsten. Om både ids och queryparametrar anges kommer tjänsten att ignorera queryparametern och kommer endast att försöka ta bort datakort baserat på ids-parametern.

Exempel på begäran och svar, radering av datakort med enhets-ID

Begäran

Tjänst: delete.ws

URL-exempel:
https://localhost:8080/esm/delete.ws?ids=15021

Svar

<?xml version="1.0" encoding="utf-8"?>
<entity-delete-report>
   <successful-deletions count="1"/>
   <failed-deletions count="0"/>
</entity-delete-report>

Exempel på begäran och svar, borttagning av datakort med hjälp av EQL

Begäran

Tjänst: delete.ws

EQL : SELECT $efecte_id$, $subject$, $status$ FRÅN entitet WHERE entity.template.code = 'incident' OCH $efecte_id$='INC-000270'

URL-exempel:
https://localhost:8080/esm/delete.ws?query=select%20%24efecte_id%24%20%2C%24subject%24%2C%20%24status%24%20from%20entity%20where%20entity.template.code%20%3D%20'incident'%20and%20%24efecte_id%24%3D'INC-000270'

Svar

<?xml version="1.0" encoding="utf-8"?>
<entity-delete-report>
   <successful-deletions count="1"/>
   <failed-deletions count="0"/>
</entity-delete-report>

Söktjänst

För att söka i datakort erbjuder Efecte en dataCardSearch-webbtjänst som tar en EQL fråga (Efecte Query Language) och returnerar resultaten som XML. Se kapitel 2 för mer information om hur man konstruerar EQL -frågor.

XML-filen som returneras av söktjänsten finns i ett av följande tre format:

• Entitets-XML
• Mall-XML
• "Generisk" XML

Entitets-XML och mall-XML beskrivs i dokumentet Efecte XML Schema Description . Det "generiska" XML-formatet beskrivs med exempel nedan. Observera att det generiska formatet kan innehålla fullständiga instanser av Entitets-XML och mall-XML, beroende på EQL frågan.

Datumvärden returneras alltid i formatet åååå-MM-dd HH:mm:ss z , enligt ISO 8601-standarden. Observera att tidszonsnamnet ingår i slutet. Den tidszon som används är alltid JVM:s eller databasens standardtidszon. Observera att om "stöd för flera tidszoner" är aktiverat kan detta skilja sig från Entity XML, där datum- och tidsvärden justeras efter webbtjänstanvändarens tidszonsinställning.

I decimaltal används en punkt (.) som decimalavgränsare. Teckenkodningen som används i svars-XML:n beror på ramverksegenskapen webservice.response.encoding . Standardkodningen är UTF-8.

Om det inte finns något behov av att visa borttagna eller dolda datakort, använd entity.deleted=0 eller entity.hidden=0 i frågeparametern.

Generiskt resultat-XML

Möjliga datatypelement för generiska sökresultat:

HTTP-parametrar

HTTP-parametrar för söktjänster:

Exempel på begäran och svar, returnerar endast namn på enheter

Ett dokument som består av <string>-värden, direkt under <result>-elementet, returneras som svar på den enkla EQL frågan.

Begäran

Tjänst: search.ws

EQL : SELECT entity.name FROM entity WHERE entity.folder.name = 'Incidenthantering'

URL-exempel:
https://localhost:8080/esm/search.ws?query=select%20entity.name%20from%20entity%20where%20entity.folder.name%20%3D%20'Hantering av incidenter'

Svar

<?xml version="1.0" encoding="UTF-8" ?>
<result>
   <string>Problems in CRM</string>
   <string>Mobile phone not working</string>
   <string>Test incident</string>
   <string>API incident</string>
</result>

Exempel på begäran och svar, med hjälp av mallens attributkoder

När man väljer flera fält grupperas resultaten med hjälp av element. Observera att ordningen på strängarna inom raden är samma som attributordningen i select (positionerna är bundna).

Begäran

Tjänst: search.ws

EQL : SELECT $efecte_id$, $subject$, $status$ FRÅN entitet WHERE entity.template.code = 'incident'

URL-exempel:
https://localhost:8080/esm/search.ws?query=select%20%24efecte_id%24%20%2C%24subject%24%2C%20%24status%24%20from%20entity%20where%20entity.template.code%20%3D%20'incident'

Svar

<?xml version="1.0" encoding="UTF-8" ?>
<result>
   <row>
       <string>INC-000270</string>
       <string> Problems in CRM </string>
       <string>1 - Untouched</string>
   </row>
   <row>
       <string>INC-000273</string>
       <string>Mobile phone not working</string>
       <string>1 - Untouched</string>
   </row>
   <row>
       <string>INC-000272</string>
       <string>Test incident </string>
       <string>2 - Solving</string>
   </row>
</result>

Exempel på begäran och svar, returmappnamn och referensdatamål

I det här fallet inkluderar den generiska resultat-XML:n fullständiga Entity XML-dokument "inbäddade" i den, tillsammans med enkla <string>-värden:
Begäran

Tjänst: search.ws

EQL : SELECT entity.mapp.namn, entity.referensData.mål FRÅN entity WHERE entity.mallId = 2597

URL-exempel:
https://localhost:8080/esm/search.ws?query= select%20entity.folder.name%2C%20entity.referenceData.target%20from%20entity%20where%20entity.templateId%20%3D%202597

Svar

<?xml version="1.0" encoding="UTF-8" ?>
<result>
   <row>
       <string>Incident management</string>
       <entity id="14549" name="18.06.2018 09:03">
           <template id="5604" name="ValueChange" code="ValueChange"/>
           <group id="834" name="system"/>
           <attribute id="5610" name="Value" code="value">
               <value>1 - Untouched</value>
           </attribute>
           <attribute id="5614" name="Modifier" code="creator">
               <value>webapi</value>
           </attribute>
       </entity>
   </row>
   <row>
       <string>Incident management</string>
       <entity id="15066" name="18.06.2018 13:56">
           <template id="5604" name="ValueChange" code="ValueChange"/>
           <group id="834" name="system"/>
           <attribute id="5610" name="Value" code="value">
               <value>1 - Untouched</value>
           </attribute>
           <attribute id="5614" name="Modifier" code="creator">
               <value>webapi</value>
           </attribute>
       </entity>
   </row>
</result>

Exempel på begäran och svar, returnera givna attribut med hjälp av attributkoder

attributkoder definierar vilka attribut som returneras i svarsmeddelandet. På så sätt returnerar inte webb- API :et attribut som användaren inte behöver.

Begäran

Tjänst: search.ws

EQL : VÄLJ entitet FRÅN entitet WHERE template.code='arbetsstation'

Attributkoder: effekt_id, arbetsstationsmodell, status

URL-exempel:
https://localhost:8080/esm/search.ws?attributeCodes=efecte_id,workstation_model,status&query=select%20entity%20from%20entity%20where%20template.code%20%3D%20'arbetsstation'

Svar

<?xml version="1.0" encoding="UTF-8" ?>
<entityset>
   <entity id="19103" name="Test User">
       <template id="1622" name="Workstation" code="workstation"/>
       <group code="asset"/>
       <attribute id="1628" name="Device model" code="workstation_model">
           <reference id="19125" name="MacBook Pro 15"/>
       </attribute>
       <attribute id="1380" name="Status" code="status">
           <value>2 - In use</value>
       </attribute>
       <attribute id="1311" name="Efecte ID" code="efecte_id">
           <value>WS-000148</value>
       </attribute>
   </entity>
</entityset>

FileMetaData-tjänst

Filmetadatatjänsten används för att hämta information om bifogade filer som är bifogade ett datakort. Om datakortet innehåller flera fält med bilagor returneras information om alla dessa bilagor samtidigt. Detta gör API mindre utdraget.

Sedan Efecte 4.2 returnerar metadatatjänsten inte bara namn utan även visningsnamn för varje bilaga. Namn är ett internt filnamn (t.ex. "20180717_1.xml") som används som identifierare vid förfrågningar till filnedladdningstjänsten (se nästa avsnitt). Visningsnamn är det ursprungliga namnet på den bifogade filen, vilket vanligtvis är mer lättläst (t.ex. "readme.txt").

HTTP-parametrar

HTTP-parametrar för FileMetaData-tjänsten:

Exempel på begäran och svar

Begäran

Tjänst: fileMetadata.ws

URL-exempel:
https://localhost:8080/esm/fileMetadata.ws?entityId=15048

Svar

<?xml version="1.0" encoding="utf-8"?>
<entity-attachment-metadata>
   <entity id="15048">
       <attribute id="2696" code="file_attachments">
           <attachment>
               <name>20180717_1.xml</name>
               <displayname>test.xml</displayname>
               <size>4871</size>
               <last-modified>2018-07-17 09:35:12 EEST</last-modified>
           </attachment>
       </attribute>
   </entity>
</entity-attachment-metadata>

Filnedladdningstjänst

Filnedladdningstjänsten används för att ladda ner filer som är bifogade till datakort som finns i Efecte. Filer returneras i HTTP-svaret.

Klienten bör alltid först kontrollera HTTP-statuskoden för svaret. Svarets innehåll kan tolkas som den begärda filen endast när statuskoden är "200 OK". Andra statuskoder som tjänsten vanligtvis anger är:

• 400 Felaktig begäran – Om några av de obligatoriska parametrarna saknas.
• 403 Förbjuden – Om webbtjänstanvändaren inte har behörighet för det angivna.
• Datakort eller attribut.
• 404 Hittades inte – Om den begärda filen inte hittades.

I dessa felsituationer är HTTP-svarstexten ett XML-felmeddelande med mer detaljerad information.

HTTP-parametrar

HTTP-parametrar för FileDownload-tjänsten:

Exempel på begäran och svar

Begäran

Tjänst: fileDownload.ws

URL-exempel:
https://localhost:8080/esm/fileDownload.ws?entityId=15048&attributeId=2696&fileName=20180717_1.xml

Svar

I det här fallet visar svaret data från filen

<?xml version="1.0" encoding="UTF-8"?>
<inventory>
   <item>
       <title>Computer</title>
       <price>1000</price>
       <company>Customer</company>
   </item>
<inventory>

Filuppladdningstjänst

Filuppladdningstjänsten används för att ladda upp filer till ett Efecte-datakort. Filuppladdningstjänsten analyserar HTTP-förfrågningar som överensstämmer med RFC 1867, "Form-based File Upload in HTML". Det vill säga om en HTTP-förfrågan skickas med POST-metoden och med innehållstypen "multipart/form-data". Det är möjligt att skicka flera filer samtidigt, om det behövs.

Datakortet måste skapas innan filen kan laddas upp till det! FileUpload-tjänsten skapar inte ett nytt datakort.

HTTP-parametrar

HTTP-parametrar för FileUpload-tjänsten:

Exempel på begäran och svar

Begäran

Tjänst: fileUpload.ws

URL-exempel:
https://localhost:8080/esm/fileUpload.ws?entityId=14938&attributeId=2696&operationType=set

Innehållstyp: flerdelad/formulärdata

Svar

<?xml version="1.0" encoding="utf-8"?>
<attachment-upload-result>
   <attachment>
       <name>20180717_15.xml</name>
   </attachment>
</attachment-upload-result>

Steg-för-steg-exempel på att skapa ett datakort och ladda upp en fil till det

Detta steg-för-steg-exempel visar alla steg som krävs för att ladda upp en fil från ingenting. Viktiga attribut är markerade med fetstil. Det består av följande steg:

1. Importerar (skapar) datakort.
2. Frågar efter datakortets entitets-ID.
3. Ta reda på mallar attributId för attributet för filbilaga.
4. Laddar upp fil till datakort som skapades.

Första datakortet måste skapas:

Begäran

Tjänst: dataCardImport.ws

URL-exempel:
https://localhost:8080/esm/dataCardImport.ws?mappkod=incident_management

Meddelandetext:

<entityset>
 <entity>
     <template code="incident"/>
     <attribute code="subject">
       <value>File upload test</value>
     </attribute>
     <attribute code="impact">
       <value>3. Low</value>
     </attribute>
     <attribute code="urgency">
       <value>3. Low</value>
     </attribute>
 </entity>
</entityset>

Svar

<?xml version="1.0" encoding="utf-8"?>
<entity-import-report>
   <start-time>04.09.2018 08:27:29</start-time>
   <total-time>0,602</total-time>
   <entities-handled-per-second>1,661</entities-handled-per-second>
   <average-entity-handling-time>0,602</average-entity-handling-time>
   <user>webapi</user>
   <entities-handled>1</entities-handled>
   <entities-saved>1</entities-saved>
   <entities-updated>0</entities-updated>
   <entities-created>1</entities-created>
</entity-import-report>

Innan en fil kan laddas upp måste entityId och attributeId vara kända för filbilagor till datakortet som just skapades. Nedan följer en fråga som kan användas för att hämta entityId och även för att validera annan data:

Begäran

Tjänst: search.ws

EQL : VÄLJ entitet FRÅN entitet WHERE template.code='incident' OCH $created$>'NOW-1m' OCH $created$<'NOW'
Attributkoder: efecte_id,file_attachments,status,ämne,beskrivning,skapad

URL-exempel:
https://localhost:8080/esm/search.ws?attributeCodes=efecte_id,file_attachments,status,ämne,beskrivning,skapad&query=select%20entity%20from%20entity%20where%20template.code%3D'incident'%20and%20%24created%24%3E'NOW-1m'%20and%20%24created%24%3C'NOW'

Svar

<?xml version="1.0" encoding="UTF-8" ?>
<entityset>
   <entity id="19221" name="File upload test">
       <template id="2597" name="Incident" code="incident"/>
       <group code="incident_management"/>
       <attribute id="2612" name="Incident ID" code="efecte_id">
           <value>INC-000275</value>
       </attribute>
       <attribute id="2623" name="Status" code="status">
           <value>1 - Untouched</value>
       </attribute>
       <attribute id="2632" name="Subject" code="subject">
           <value>File upload test</value>
       </attribute>
       <attribute id="2789" name="Created" code="created">
           <value>04.09.2018 08:27</value>
       </attribute>
   </entity>
</entityset>

AttributeId kan hämtas, till exempel med följande metoder:

Via administrationssidan , välj rätt mall och redigera attributet vars attributeId vi behöver. När attributet öppnas är id siffrorna efter den sista /, t.ex.:
https://localhost:8080/esm/EfecteFrameset.do#/admin/templates/edit/2597/2680/2696

Använder söktjänsten för att hämta mallschema.

Frågar efter mallschema:

Begäran

Tjänst: search.ws

EQL : VÄLJ mall FRÅN mall DÄR mall.kod='incident'

URL-exempel:
https://localhost:8080/esm/search.ws?query=select%20template%20from%20template%20where%20template.code='incident'

Svar
Från svaret behöver vi hitta <attribute> där <code> är attributet code för file attachment attributet och från detta attribut vill vi få värdet för <class-attribute-id> , som:

…
<attribute>
               <id>2695</id>
               <class-attribute-id>2696</class-attribute-id>
               <code>file_attachments</code>
               <name>File attachments</name>
…

Nu när vi har entityId och attributeId kan vi ladda upp filen:

Begäran

Tjänst: fileUpload.ws

URL-exempel:
https://localhost:8080/esm/fileUpload.ws?entityId=19221&attributeId=2696&operationType=set

Innehållstyp: flerdelad/formulärdata

Svar

<?xml version="1.0" encoding="utf-8"?>
<attachment-upload-result>
   <attachment>
       <name>20180904_1.xml</name>
   </attachment>
</attachment-upload-result>

Hämtar datakortschema

Efecte-datakortmetadata, dvs. information om vilka fält det kan innehålla och deras egenskaper, kan nås via webbtjänsten dataCardSearch med en EQL -fråga till mallarna. Här är ett exempel på en EQL -fråga som väljer alla mallar:

VÄLJ mall FRÅN mall

URL-exempel:
https://localhost:8080/esm/search.ws?query=select%20template%20from%20template%20where%20template.code='incident'

Säkerhet

Kryptering

HTTP-grundautentisering skickar inloggningsuppgifter som klartext, så det är viktigt att använda HTTPS.

Autentisering

Efecte webb API tjänster autentiseras med hjälp av HTTP-grundautentisering. Du måste skapa inloggningsuppgifter till Efecte för att använda webbtjänster. (I behörighetsträdet skapar du en roll som har behörighet att använda Efecte webb- API -tjänster och lägger till en eller flera användare till den rollen.) Alla åtgärder utförs med behörigheterna för den autentiserade Efecte-användaren. Dessa behörigheter definierar vilka mallar, attribut och mappar webbtjänstanvändaren har åtkomst till.

Root-användaren bör inte användas som en Web API användare, eftersom den har åtkomst till allt, därför kan det vara farligt att använda root. När man undersöker problem med Web API kan det dock vara bra att uppgradera Web API användaren till root-nivå, bara för att kontrollera om det finns problem med behörigheter eller om problemen orsakas av själva Web API -begäran.

Skapar Web API användare

• Skapa roll och välj produktbehörighet för Web API .
• Lägg till mappbehörigheter till rollen.
• Lägg till mallbehörigheter till rollen.
• Skapa webb- API användare.
• Lägg till användare till en tidigare skapad roll.
• Testa att du kan utföra önskade operationer via webb API . Du kan göra detta i webbläsaren med /search.ws?query=select count(id) från entiteten.