Versie: Versie 22

REST API

Met de REST API van de Principal Toolbox kunnen beheerders en ontwikkelaars externe systemen programmatisch koppelen aan de Principal Toolbox. Dit artikel behandelt authenticatie, het formatteren van requests, alle beschikbare endpoints en foutafhandeling.

Aan de slag

Deze sectie behandelt de basisvereisten voor het doen van API-calls: de opbouw van de base-URL, de authenticatieflow, verplichte headers, foutmeldingen en de regels voor dataformattering.

Opbouw van de base-URL

Alle API-endpoints volgen dit URL-patroon:

{baseurl}/service/fortesipm/{objecttype}/{crud}/{context}

Segment	Omschrijving
`{baseurl}`	De hoofd-URL van je Principal Toolbox-omgeving (bijv. `https://client.principaltoolbox.com`)
`{objecttype}`	Het type object waarop de actie wordt uitgevoerd (bijv. `node`, `entry`, `user`)
`{crud}`	Het type bewerking: `read`, `create`, `update` of `delete`
`{context}`	De specifieke actie of scope (bijv. `instance`, `list`, `descendants`)

Voorbeeld:

https://client.principaltoolbox.com/service/fortesipm/node/read/descendants

Authenticatie

Authenticatie verloopt via een tokengebaseerde flow. Vraag eerst een token op via het inloggen en neem dit token vervolgens op in alle volgende requests.

Stap 1: Een token opvragen

Stuur een POST-request naar:

POST {baseurl}/service/fortesipm/login

Request body:

{
  "username": "someUsername",
  "password": "somePassword"
}

Een succesvolle login retourneert HTTP 200 met de volgende response body:

{
  "status": { "code": 101, "text": "SUCCESSFUL" },
  "message": "Successful lease",
  "details": {
    "loginMessage": "Logged in",
    "authToken": "NmZmNDM1YTEt...",
    "username": "someUsername",
    "userDisplayName": "Display Name",
    "userID": 1234,
    "administrator": false
  }
}

Een mislukte login retourneert HTTP 403.

Stap 2: Het token gebruiken

Neem de waarde van authToken op in elke volgende request via de volgende header:

PTB-Rest-Authorization: Basic {TOKEN}

Let op: De Principal Toolbox vereist minimaal JVM-versie 1.7 voor 4096-bit SSL-verbindingen.

Verplichte headers

Header	Waarde	Wanneer verplicht
`Content-Type`	`Application/JSON;charset=UTF-8`	Alle JSON-request bodies
`PTB-Rest-Authorization`	`Basic {TOKEN}`	Alle calls behalve inloggen

Laat bij multipart-requests (documentupload) de Content-Type-header weg en laat de HTTP-client deze automatisch instellen.

Foutafhandeling

Als een request mislukt, retourneert de API HTTP 400 met een RestStatus-object in de response body:

{
  "status": { "code": 102, "text": "FAILURE" },
  "message": "This is an error message"
}

Statuscodes:

Code	Tekst	Omschrijving
`101`	`SUCCESSFUL`	De request is succesvol afgerond
`102`	`FAILURE`	Er is een algemene fout opgetreden
`501`	`LEASE SUCCESSFUL`	Het object is succesvol geleaset (vergrendeld)
`502`	`LEASE FAILURE`	Het object is al vergrendeld door een andere gebruiker

Wanneer een 502 Lease Failure optreedt, bevat de response aanvullende details:

{
  "status": { "code": 502, "text": "LEASE FAILURE" },
  "message": "Object is locked",
  "details": {
    "lockedOn": "2024-01-15T10:30:00",
    "lockedBy": "someUsername",
    "leaseTime": 300
  }
}

Dataformaten

Type	Formaat	Voorbeelden
Codering	UTF-8	—
Datums	`YYYY-MM-DD`	`2015-08-04`
Getallen	`[-]#[.##]`	`450`, `2031.40`, `-12.3`
JSON	RFC7159-compliant	—
CSV (import/export)	Header-rij verplicht; geen spaties in kolomnamen; tekst- en memo-waarden tussen aanhalingstekens	—

Verwijder bij het doorgeven van XML binnen een JSON-parameter alle tabs, regeleinden en comments uit de XML voordat je deze codeert als JSON-stringwaarde.

Instances

De instance-endpoints lezen en schrijven individuele nodes of verzamelingen van nodes binnen de objectboom van de Principal Toolbox.

Instance lezen

Beschikbaar: 6.0+

Retourneert de data van één node op basis van het ID.

GET {baseurl}/service/fortesipm/node/read/instance/{id}

Parameter	Type	Omschrijving
`id`	URL	Het ID van de op te halen node

De response bevat de nodeTypeName, nodeTypeID en id van de node, en alle veldwaarden.

Voorbeeld:

GET {baseurl}/service/fortesipm/node/read/instance/48826857

Lijst lezen

Beschikbaar: 6.0+

Retourneert alle nodes van een gegeven type, systeembreed. Dit endpoint is niet beperkt tot een specifieke locatie en is daarom geschikt voor het ophalen van financiële categorieën, skills en andere globale nodetypes.

POST {baseurl}/service/fortesipm/node/read/list/{nodeTypeName}

Parameter	Type	Omschrijving
`nodeTypeName`	URL	Het te tonen nodetype (bijv. `P2Project`, `PlanItem`)

POST-bodyparameters (allemaal optioneel):

Parameter	Omschrijving
`viewXml`	Een view-definitie-XML voor filtering en indeling. Indien weggelaten, worden alle velden zonder filter geretourneerd.
`fieldNames`	Kommagescheiden lijst van veldnamen om te retourneren (bijv. `"Name,Description,FolderID"`)
`sortFields`	Kommagescheiden veldnamen om op te sorteren
`sortDirections`	Sorteerrichting per sorteerveld: `ASC` of `DESC`

Voorbeeld met viewXml-filter (de XML moet op één regel staan, zonder tabs of regeleinden):

{
  "viewXml": "<listing id='0'><filter><Name operator='equals' filterValues='Test issue' /></filter><layout><header /><row><cell name='Name' /><cell name='Description' /><cell name='FolderID' /></row></layout></listing>"
}

Voorbeeld met alleen fieldNames:

{
  "fieldNames": "Name,Description,FolderID"
}

Afstammelingen lezen

Beschikbaar: 7.0+

Retourneert alle nodes van een gegeven type binnen de scope van een bovenliggende locatie. De resultaten worden geretourneerd als platte (niet-hiërarchische) lijst.

POST {baseurl}/service/fortesipm/node/read/descendants/{id}/{type}

Parameter	Type	Omschrijving
`id`	URL	Het ID van de bovenliggende node (bepaalt de scope)
`type`	URL	De naam van het te retourneren nodetype

De POST-bodyparameters zijn dezelfde als bij Lijst lezen: viewXml, fieldNames, sortFields, sortDirections. Allemaal optioneel.

Recursief lezen

Beschikbaar: 7.0+

Retourneert een hiërarchische (geneste) JSON-structuur van nodes. Vergelijkbaar met Afstammelingen lezen, maar behoudt de boomstructuur. De rootnode is altijd inbegrepen in het resultaat.

POST {baseurl}/service/fortesipm/node/read/recursive/{id}/{type}/{relation}

Parameter	Type	Omschrijving
`id`	URL	Het ID van de rootnode
`type`	URL	De naam van het nodetype
`relation`	URL	Het relatietype: `normal`, `planning` of `breakdown`

POST-bodyparameters:

Parameter	Omschrijving
`fieldNames`	Kommagescheiden lijst van veldnamen om te retourneren (optioneel)

Voorbeeld:

POST {baseurl}/service/fortesipm/node/read/recursive/1455/PlanItem/planning

Instance bijwerken

Beschikbaar: 8.5+

Werkt één of meer velden bij op een bestaande node.

POST {baseurl}/service/fortesipm/node/update/instance/{nodeTypeName}/{id}

Parameter	Type	Omschrijving
`nodeTypeName`	URL	De naam van het nodetype
`id`	URL	Het ID van de bij te werken node

Let op: Het oudere endpoint /node/update/instance/{id} (zonder nodeTypeName) is verouderd sinds versie 8.5.0. Gebruik de bovenstaande vorm.

Neem in de request body alleen de velden op die je wilt wijzigen:

{
  "Remarks": "Remarks on this instance",
  "Custom2": "123456"
}

Instance aanmaken

Beschikbaar: 6.0+

Maakt een nieuwe node aan op de opgegeven locatie. Niet elk nodetype kan op elke locatie worden aangemaakt.

POST {baseurl}/service/fortesipm/node/create/instance/{parentId}/{type}

Parameter	Type	Omschrijving
`parentId`	URL	Het ID van de bovenliggende node waaronder de nieuwe instance wordt geplaatst
`type`	URL	De naam van het aan te maken nodetype

Geef de veldwaarden voor de nieuwe node op in de request body:

{
  "Description": "REST call does not respond when connection is lost",
  "Remarks": "Remarks on this issue",
  "Custom2": "123456"
}

Instances aanmaken (systeembreed)

Beschikbaar: 8.5.3+

Maakt een systeembrede node aan, niet gekoppeld aan een specifieke locatie. Gebruik dit alleen voor nodetypes die specifiek zijn ontworpen voor systeembrede aanmaak, zoals CurrencyRate.

POST {baseurl}/service/fortesipm/node/create/instances/{type}

Parameter	Type	Omschrijving
`type`	URL	De naam van het nodetype (bijv. `CurrencyRate`)

Voorbeeld:

{
  "Startdate": "2018-01-01",
  "Currency": 5678980,
  "Rate": 123.456
}

Let op: Gebruik dit endpoint alleen wanneer dit specifiek wordt geadviseerd. Gebruik voor de meeste nodetypes Instance aanmaken met een bovenliggende locatie.

Metadata

De metadata-endpoints retourneren velddefinities en beschikbare waarden voor nodetypes.

Metadata lezen

Beschikbaar: 6.0+

Retourneert de metadata van een nodetype: veldnamen, weergavenamen, types, bewerkbaarheid en selectwaarden voor statische selectvelden. Responses worden gecachet.

POST {baseurl}/service/fortesipm/node/read/metadata/{nodeTypeName}

Parameter	Type	Omschrijving
`nodeTypeName`	URL	Het nodetype waarvoor je de metadata wilt ophalen

Er zijn geen POST-bodyparameters vereist.

Voorbeeldrespons:

{
  "id": 6001,
  "name": "Issue",
  "displayName": "Issue",
  "pluralDisplayName": "Issues",
  "fields": {
    "Name": {
      "displayName": "Name",
      "type": "string",
      "isEditable": true
    },
    "Custom2": {
      "displayName": "Custom 02",
      "type": "int",
      "isCustom": true,
      "displayWidth": 60,
      "isEditable": true
    },
    "Custom7": {
      "displayName": "Custom 07",
      "type": "string",
      "inputType": "select",
      "isCustom": true,
      "displayWidth": 100,
      "isEditable": true,
      "selectvalues": [
        { "value": "1", "displayName": "one" },
        { "value": "2", "displayName": "two" }
      ]
    }
  }
}

Beschikbare selectwaarden lezen

Beschikbaar: 6.0+

Retourneert de waarden voor een dynamisch selectveld. Dynamische selectwaarden zijn niet opgenomen in de standaard metadatarespons, dus dit endpoint is nodig om ze op te halen.

POST {baseurl}/service/fortesipm/node/read/metadata/selectvalues/{id}/{fieldName}/{nodeTypeName}

Parameter	Type	Omschrijving
`id`	URL	Het ID van de topniveau-node (bijv. een project) die de context voor de selectwaarden bepaalt
`fieldName`	URL	De naam van het selectveld
`nodeTypeName`	URL	Het nodetype waartoe het veld behoort

Boekingen

De boekingsendpoints retourneren tijd- en kostenboekingen die aan een locatie zijn gekoppeld.

Boekingslijst lezen

Beschikbaar: 6.0+

Retourneert individuele boekingen (uren, kosten) voor een gegeven locatie.

POST {baseurl}/service/fortesipm/entry/read/list/{id}

Parameter	Type	Omschrijving
`id`	URL	Het ID van de locatienode

POST-bodyparameters:

Parameter	Verplicht	Omschrijving
`viewXml`	Ja	View-definitie-XML met filter en indeling

De viewXml ondersteunt filteroperators, sorteren via de attributen sortfield en sortdirection op het <filter>-element, en een completelist-vlag.

Voorbeeld:

{
  "viewXml": "<listing id='0'><filter sortfield='Resource,Type,PeriodStartdate' sortdirection='ASC,ASC,ASC' completelist='true'><ValueType operator='in' filterValues='Available,Allocation' /><PeriodStartdate operator='bigger' filterValues='today' /></filter><layout><header /><row><cell name='Resource' /><cell name='Type' /><cell name='PeriodStartdate' /><cell name='Hours' /></row></layout></listing>"
}

Boekingstimeline lezen

Beschikbaar: 6.0+

Groepeert boekingen in periodes. Breid de viewXml uit met een <timeline>-sectie om de periodestructuur te definiëren.

POST {baseurl}/service/fortesipm/entry/read/timeline/{id}

Parameter	Type	Omschrijving
`id`	URL	Het ID van de locatienode

Voeg een <timeline>-sectie toe aan de viewXml:

<timeline>
  <startdate>today</startdate>
  <intervals>5</intervals>
  <scale>weeks</scale>
</timeline>

Waarde van `scale`	Omschrijving
`days`	Eén kolom per dag
`weeks`	Eén kolom per week
`months`	Eén kolom per maand

Voeg doPivoting='true' toe aan het <layout>-element om gepivoteerde output te retourneren. Pivotkolommen worden dynamisch geretourneerd als PVT{date}-velden in de response.

Documenten

De documentendpoints beheren bestandsbijlagen en koppelingen die aan nodes zijn gekoppeld.

Document toevoegen

Beschikbaar: 8.0.3+

Koppelt een document, link of bestand aan een node. De request moet gebruikmaken van het content type multipart. Voor dit endpoint wordt geen standaard JSON content type gebruikt.

POST {baseurl}/service/fortesipm/node/create/instance/{id}/Document

Parameter	Type	Omschrijving
`id`	URL	Het ID van de node waaraan het document wordt gekoppeld

De multipart request body bestaat uit twee onderdelen:

Onderdeel	Type	Inhoud
Parameters	`text`	JSON-object met `FileType`, `Name` en type-specifieke velden
File	`file`	UU-gecodeerde bestandsinhoud (alleen voor daadwerkelijke bestandsuploads)

FileType-opties:

FileType	Doel	Aanvullend verplichte velden
`internaldocument`	Koppeling naar een bestaand document in de toolbox	`InternalLinkID`
`externaldocumentlink`	Koppeling naar een externe REST-service	`ExternalDocumentLink`
`hyperlink`	Generieke URL-koppeling	`Url`
MIME type (bijv. `application/msword`)	Bestand uploaden	`ActualFileName`

Ondersteunde MIME-types voor bestandsupload:

MIME-type	Extensie
`application/msword`	`.doc`
`application/vnd.openxmlformats-officedocument.wordprocessingml.document`	`.docx`
`application/vnd.ms-excel`	`.xls`
`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`	`.xlsx`
`application/vnd.ms-powerpoint`	`.ppt`
`application/vnd.openxmlformats-officedocument.presentationml.presentation`	`.pptx`
`application/octet-stream`	Overige bestandstypes

Voorbeeld: een hyperlink toevoegen:

{
  "FileType": "hyperlink",
  "Name": "Example Link",
  "Url": "http://www.example.com/link?par1=test"
}

Document bijwerken

Beschikbaar: 8.0.3+

Werkt een bestaande documentbijlage bij. Gebruikt dezelfde multipart-structuur als Document toevoegen.

POST {baseurl}/service/fortesipm/node/update/instance/{id}

Parameter	Type	Omschrijving
`id`	URL	Het ID van de documentnode (niet de bovenliggende locatie)

Berichten

Meldingsbericht verzenden

Beschikbaar: 7.0+

Verzendt een bericht op de opgegeven locatie. De geauthenticeerde gebruiker wordt automatisch als mention toegevoegd.

POST {baseurl}/service/fortesipm/message/send/{id}

Parameter	Type	Omschrijving
`id`	URL	Het ID van de locatienode waar het bericht wordt geplaatst

POST-bodyparameters:

Parameter	Verplicht	Omschrijving
`message`	Ja	De berichttekst. HTML wordt ondersteund, inclusief `<a href>`-links.
`mentions`	Nee	Array van gebruikers- of resource-ID's. Het bericht verschijnt op hun startpagina.
`hashtags`	Nee	Array van map- of node-ID's. Het bericht verschijnt op die locaties.

Voorbeeld:

{
  "message": "<p>Test message that may contain HTML</p>",
  "mentions": ["8129701", "221345"],
  "hashtags": ["563655"]
}

Importeren en exporteren

De import- en exportendpoints voeren taken uit die vooraf zijn geconfigureerd in de Principal Toolbox. Voor beide endpoints zijn beheerdersrechten vereist. Zie Importeren & exporteren voor uitleg over het configureren van taken.

Importtaak uitvoeren

Beschikbaar: 8.0.1+

Voert een geconfigureerde importtaak uit met de opgegeven data. Via dit endpoint wordt alleen CSV-formaat ondersteund.

POST {baseurl}/service/fortesipm/integration/import/execute/{id}

Parameter	Type	Omschrijving
`id`	URL	Het ID van de uit te voeren importtaak

De request body bevat ruwe CSV-data, geen JSON:

"column1";"column2"
"value1a";"value1b"
"value2a";"value2b"

Een succesvolle response bevat een veld details.log met het importresultaat, en de booleans errors en warnings.

Exporttaak uitvoeren

Beschikbaar: 8.0.1+

Voert een geconfigureerde exporttaak uit en retourneert de exportdata direct (doorgaans CSV).

GET {baseurl}/service/fortesipm/integration/export/execute/{id}

Parameter	Type	Omschrijving
`id`	URL	Het ID van de uit te voeren exporttaak

Er zijn geen POST-bodyparameters vereist.

Gebruikersbeheer

Voor de endpoints voor gebruikersbeheer zijn beheerdersrechten vereist. Wachtwoorden kunnen niet worden ingesteld of gewijzigd via de REST API.

Gebruiker aanmaken

Beschikbaar: 8.0.1+

Maakt een nieuw gebruikersaccount aan.

POST {baseurl}/service/fortesipm/user/create/instance

POST-bodyparameters:

Parameter	Verplicht	Omschrijving
`UserName`	Ja	Gebruikersnaam om in te loggen
`Lastname`	Ja	Achternaam
`Email`	Ja	E-mailadres
`IsGroup`	Nee	Stel in op `true` om een gebruikersgroep aan te maken
`Initials`	Nee	Initialen van de gebruiker
`Firstname`	Nee	Voornaam
`ResourceFolderID`	Nee	Maakt de gebruiker aan vanuit een bestaande resource
`SendEmail`	Nee	Stel in op `true` om een uitnodigingsmail te verzenden
`EmailRemarks`	Nee	Aangepaste tekst om op te nemen in de uitnodigingsmail

Let op: Het veld Passwd wordt niet geaccepteerd. Gebruik SendEmail: true om een uitnodigingsmail te versturen zodat een gebruiker kan inloggen.

Gebruiker bijwerken

Beschikbaar: 8.0.1+

Werkt een bestaand gebruikersaccount bij. Neem alleen de te wijzigen velden op.

Bijwerken op basis van gebruikers-ID:

POST {baseurl}/service/fortesipm/user/update/instance/{id}

Bijwerken op basis van veldwaarde:

POST {baseurl}/service/fortesipm/user/update/instance/{fieldname}/{fieldvalue}

Parameter	Type	Omschrijving
`id`	URL	Het ID van de gebruikersnode
`fieldname`	URL	Het veld waarop wordt gematcht (bijv. `Custom1`)
`fieldvalue`	URL	De waarde waarop wordt gematcht

Voorbeeld: bijwerken op basis van een customveld:

POST {baseurl}/service/fortesipm/user/update/instance/Custom1/jsmith98

Request body:

{
  "Initials": "J.",
  "Firstname": "Jeremiah"
}

Let op: Zorg dat de veldwaarde die je gebruikt om op te matchen uniek is voor alle gebruikers.

Gebruiker verwijderen (deactiveren)

Beschikbaar: 8.0.1+

Deactiveert een gebruikersaccount. De data van de gebruiker blijft bewaard.

Verwijderen op basis van gebruikers-ID:

GET {baseurl}/service/fortesipm/user/delete/instance/{id}

Verwijderen op basis van veldwaarde:

GET {baseurl}/service/fortesipm/user/delete/instance/{fieldname}/{fieldvalue}

Parameter	Type	Omschrijving
`id`	URL	Het ID van de gebruikersnode
`fieldname`	URL	Het veld waarop wordt gematcht
`fieldvalue`	URL	De waarde waarop wordt gematcht

Event triggers

Event triggers roepen automatisch externe systemen aan wanneer bepaalde acties plaatsvinden in de Principal Toolbox. Voor de configuratie moet een systeeminstelling worden toegevoegd door een systeembeheerder.

Webhook voor het aanmaken van projecten

Beschikbaar: 8.0.1+

Activeert een HTTP POST naar een geconfigureerde URL wanneer een project succesvol wordt aangemaakt.

Voeg de volgende systeeminstelling toe om deze webhook te activeren:

<Setting>
  <SettingName>CreateProjectWebhookUrl</SettingName>
  <SettingValue>http://mywebhook:8080/something/somethingelse</SettingValue>
</Setting>

Wanneer een project wordt aangemaakt, stuurt de Principal Toolbox de volgende body naar de geconfigureerde URL:

{
  "id": 123456
}

Waarbij id het ID is van het nieuw aangemaakte project. Gebruik Instance lezen om de volledige projectgegevens op te halen.

De response van de webhook wordt genegeerd, maar bij een fout wel gelogd. Logs zijn toegankelijk voor systeembeheerders.

Let op: HTTPS wordt alleen ondersteund voor certificaten die worden vertrouwd door de JVM/Tomcat. Neem voor HTTP basic authentication de inloggegevens op in de URL: http://username:password@host.

Externe documentgeneratie

Beschikbaar: 8.0.3+

Activeert een HTTP POST wanneer een gebruiker een extern document genereert vanuit de sectie automatische rapportages.

Voeg de volgende systeeminstelling toe om deze trigger te activeren:

<Setting>
  <SettingName>EnableExternalDocumentLinks</SettingName>
  <SettingValue>true</SettingValue>
</Setting>

De Principal Toolbox stuurt de volgende body naar de externe service:

{
  "id": 123456,
  "personID": 123344
}

Waarbij id de locatie van het rapport is en personID het ID van de gebruiker die de actie heeft geactiveerd.

Nodetypes-referentie

Onderstaande tabel toont alle beschikbare nodetypes met hun interne ID's, algemene weergavenamen en versiebeschikbaarheid.

Name	ID	Display name	Available from	Removed in
Benefit	720	Benefit	7.0+
BudgetType	8215	Financial category
CurrencyRate	77	Currency rates
DependencyRelation	5700	Dependency
DiscussionLog	29	Discussion item
Entry	100	Generic entry	6.0+	9.5
ExportTask	21	Export task
History	10	History log
Idea	4901	Idea	7.0+
ImportTask	23	Import task
KnowledgeRepository	4	Documents & knowledge folder
Message	8003	Message	7.0+
NonProjectActivity	5502	Non project activity
NonProjectActivitySet	5500	Non project activity set
NonProjectCategory	5501	Non project category
Order	6061	Order	7.5+
OrganizationalUnit	500	Organisational unit	8.0+
P2Action	6041	Action
P2Change	6031	Change
P2Issue	6001	Issue
P2Lessonlearned	6051	Lessons learned
P2Product	5302	Classic project product		9.0
P2Program	5100	Classic MSP programme folder		9.0
P2ProgramProject	5110	Classic MSP programme project		9.0
P2ProgramTemplate	5111	Classic MSP programme model		9.0
P2Project	5000	Project
P2ProjectTemplate	5002	Project model
P2Quality	6021	Quality review
P2Risk	6011	Risk
P2Stage	5301	Classic project stage		9.0
Person	3	User account
PlanItem	5602	Plan item
Portfolio	701	Portfolio
PortfolioDashboard	711	Custom dashboard
PortfolioModel	703	Portfolio model
ProgramProject	4910	Programme	8.0+
ProgramProjectModel	4911	Programme model	8.0+
ProjectReport	5003	Portfolio item
ProjectResource	8017	Project resource
SavedProjectReport	5006	Saved portfolio item
Scenario	730	Saved portfolio scenario
Skill	16	Skill
TimeRegistrationConfiguration	5520	Time entry configuration
Timesheet	81	Time sheet
TimesheetRow	84	Time sheet row
URLFolder	400	Link (url)
UserGroup	30	User group	7.5+
Workpackage	5303	Classic project work package		9.0

Noderelaties

Relaties bepalen hoe nodes met elkaar zijn verbonden in de objectboom. Het relatietype wordt gebruikt in endpoints zoals Recursief lezen.

Normal-relatie: gebruikt voor structurele hiërarchie:

P2Project → P2Issue, P2Risk, P2Quality, P2Change, P2Action, P2Lessonlearned, Order, KnowledgeRepository → Document, Entry

Planning-relatie: gebruikt voor de Gantt-/planhiërarchie:

P2Project → PlanItem (hierarchical)

Breakdown-relatie: gebruikt voor de productdecompositiestructuur:

P2Project → PlanItem (hierarchical)

Best practices

Bewaar de authToken veilig en hergebruik deze bij volgende requests. Log opnieuw in om een nieuw token op te halen als de sessie is verlopen.
Stel altijd de header Content-Type: Application/JSON;charset=UTF-8 in op alle JSON-requests.
Verwijder tabs, regeleinden en comments uit XML voordat je deze als waarde in een JSON-parameter opneemt.
Gebruik fieldNames wanneer je alleen specifieke velden nodig hebt. Dit verkleint de omvang van de response en verbetert de prestaties.
Gebruik het endpoint /node/read/metadata/{nodeTypeName} om veldnamen en -types te achterhalen voordat je integraties bouwt.
Zorg er bij het matchen van gebruikers via een customveld voor dat de veldwaarde uniek is voor alle gebruikers.
Test alle calls met een tool zoals Postman voordat je ze in je applicatie integreert.
Import- en exporttaken moeten handmatig worden geconfigureerd in de Principal Toolbox voordat ze via de API kunnen worden uitgevoerd. Zie Importeren & exporteren.
Wachtwoorden kunnen niet worden ingesteld via de REST API. Gebruik SendEmail: true bij het aanmaken of bijwerken van gebruikers om een uitnodigingsmail te versturen.
Gebruik het nieuwere endpoint node/update/instance/{nodeTypeName}/{id} (beschikbaar vanaf 8.5) in plaats van de verouderde vorm zonder nodeTypeName.

FAQ

Hoe log ik in via de REST API? Stuur een POST naar {baseurl}/service/fortesipm/login met {"username": "...", "password": "..."}. Een succesvolle response bevat een authToken. Geef dit token mee in de header PTB-Rest-Authorization: Basic {TOKEN} bij alle volgende calls.

Welke HTTP-methode gebruikt elk endpoint? De meeste endpoints gebruiken POST. Instance lezen en alle delete-calls gebruiken GET. Controleer de methode die bij elk endpoint in dit artikel wordt vermeld.

Wat betekent een 400-response? De response body bevat een RestStatus-object met status.code en message. Code 102 duidt op een algemene fout. Code 502 duidt op een lease failure: het object is vergrendeld door een andere gebruiker.

Hoe filter ik resultaten in een list-call? Gebruik de POST-parameter viewXml met een <listing>-XML-structuur die een <filter>-element bevat. Verwijder alle tabs en regeleinden uit de XML voordat je deze codeert als JSON-string.

Kan ik een wachtwoord instellen via de REST API? Nee. Het veld Passwd wordt altijd genegeerd. Gebruik SendEmail: true bij het aanmaken of bijwerken van een gebruiker om een uitnodigingsmail te versturen.

Hoe vind ik de juiste veldnamen voor een nodetype? Roep /node/read/metadata/{nodeTypeName} aan om alle veldnamen, types en weergavenamen voor een gegeven nodetype op te halen.

Waarom krijg ik een Lease Failure (502)? Een andere gebruiker heeft het object vergrendeld. Het details-object in de response bevat lockedBy, lockedOn en leaseTime om te identificeren wie de vergrendeling heeft.

Welke versie heeft mijn endpoint nodig? Elk endpoint in dit artikel vermeldt de minimale versie onder "Beschikbaar". De meeste endpoints zijn beschikbaar vanaf versie 6.0. De vorm node/update/instance/{nodeTypeName}/{id} vereist versie 8.5+.

Kan ik overal in de boom een node aanmaken? Nee. Niet elk nodetype kan op elke locatie worden aangemaakt. Raadpleeg de sectie Noderelaties en de nodetype-tabel om geldige ouder-kindrelaties te begrijpen.

Meer support nodig?

Neem contact op met je Fortes Change Cloud-beheerder of neem contact op met Fortes Support voor hulp bij API-configuratie en integratie.

Aan de slag​

Opbouw van de base-URL​

Authenticatie​

Stap 1: Een token opvragen​

Stap 2: Het token gebruiken​

Verplichte headers​

Foutafhandeling​

Dataformaten​

Instances​

Instance lezen​

Lijst lezen​

Afstammelingen lezen​

Recursief lezen​

Instance bijwerken​

Instance aanmaken​

Instances aanmaken (systeembreed)​

Metadata​

Metadata lezen​

Beschikbare selectwaarden lezen​

Boekingen​

Boekingslijst lezen​

Boekingstimeline lezen​

Documenten​

Document toevoegen​

Document bijwerken​

Berichten​

Meldingsbericht verzenden​

Importeren en exporteren​

Importtaak uitvoeren​

Exporttaak uitvoeren​

Gebruikersbeheer​

Gebruiker aanmaken​

Gebruiker bijwerken​

Gebruiker verwijderen (deactiveren)​

Event triggers​

Webhook voor het aanmaken van projecten​

Externe documentgeneratie​

Nodetypes-referentie​

Noderelaties​

Best practices​

FAQ​

Meer support nodig?​

Aan de slag

Opbouw van de base-URL

Authenticatie

Stap 1: Een token opvragen

Stap 2: Het token gebruiken

Verplichte headers

Foutafhandeling

Dataformaten

Instances

Instance lezen

Lijst lezen

Afstammelingen lezen

Recursief lezen

Instance bijwerken

Instance aanmaken

Instances aanmaken (systeembreed)

Metadata

Metadata lezen

Beschikbare selectwaarden lezen

Boekingen

Boekingslijst lezen

Boekingstimeline lezen

Documenten

Document toevoegen

Document bijwerken

Berichten

Meldingsbericht verzenden

Importeren en exporteren

Importtaak uitvoeren

Exporttaak uitvoeren

Gebruikersbeheer

Gebruiker aanmaken

Gebruiker bijwerken

Gebruiker verwijderen (deactiveren)

Event triggers

Webhook voor het aanmaken van projecten

Externe documentgeneratie

Nodetypes-referentie

Noderelaties

Best practices

FAQ

Meer support nodig?