diff --git a/markdownpages/profit/en/update-connector.md b/markdownpages/profit/en/update-connector.md index 9270ddf..df7c3d4 100644 --- a/markdownpages/profit/en/update-connector.md +++ b/markdownpages/profit/en/update-connector.md @@ -1,29 +1,127 @@ --- author: CLN -date: 2025-11-08 +date: 2026-11-17 tags: UpdateConnector, Authentication, Authorization, Finance, Hr, Order Management title: UpdateConnector --- -An external application can add, change, or delete records in the Profit database with an UpdateConnector. Each endpoint has different options. In UpdateConnectors with subobjects, you can do a specific action on a subobject. +With an UpdateConnector, you write data to Profit: you add, update or delete records. The available operations differ per endpoint. This page explains how a message is structured and how you determine which operation (add, update or delete) is performed. -## POST +## Message structure -With HTTP POST method, you create new records in Profit with an UpdateConnector. Before the record is created, the data is checked. Examples of these checks are: +An UpdateConnector message has a hierarchical structure. Each level consists of the same building blocks: -- BSN: The BSN (Social Security Number) must pass the 11-test. -- Address: The address must have a country code. -- Financial entry: A financial entry must be balanced. This means debit and credit totals are equal. +| Part | Meaning | +|---|---| +| Object name (e.g. `FiEntryPar`) | The object you address. At the top level, this is the main object of the connector. Its name can differ from the connector name in the URL: connector `FiEntries`, for example, has main object `FiEntryPar`. | +| `Element` | One record. Use an array (`[ ... ]`) to send multiple records of the same type. | +| `Fields` | The field values of the record. | +| `Objects` | Child objects (subobjects) that belong to this record. Each subobject has the same structure. | - > HTTP 500 response means that the request content cannot be checked successfully. See also [Troubleshooting](./troubleshooting).### Example POST request +**Example:** a journal entry with three entry lines. -``` javascript +```json +{ + "FiEntryPar": { + "Element": { + "Fields": { + "Year": "2026", + "Peri": "1", + "UnId": "1", + "JoCo": "20", + "AuNu": "1" + }, + "Objects": { + "FiEntries": { + "Element": [ + { + "Fields": { + "VaAs": "2", + "AcNr": "10001", + "EnDa": "2026-01-01", + "BpDa": "2026-01-01", + "AmDe": "12100", + "AmCr": "0", + "DaEx": "2026-02-01" + } + }, + { + "Fields": { + "VaAs": "1", + "AcNr": "8010", + "EnDa": "2026-01-01", + "BpDa": "2026-01-01", + "AmDe": "0", + "AmCr": "10000", + "VaId": "1" + } + }, + { + "Fields": { + "VaAs": "1", + "AcNr": "1510", + "EnDa": "2026-01-01", + "BpDa": "2026-01-01", + "AmDe": "0", + "AmCr": "2100", + "VaId": "1" + } + } + ] + } + } + } + } +} +``` + +The header of the journal entry is in `FiEntryPar`. The entry lines are subobjects (`FiEntries`) and are sent as an array. The main record and the lines are added in one call. + +## Determining the operation + +There are three ways to determine which operation Profit performs. They range from simple to flexible. + +| Method | The operation applies to | Use it when | +|---|---|---| +| 1. HTTP method on the connector | The entire message | you add, update or delete everything | +| 2. `POST` on a subobject | One child object | you only want to add a subobject to an existing record | +| 3. `@Action` per element | Each individual record | you want to combine different operations in one message | + +### 1. HTTP method on the connector + +The HTTP method determines the default operation for the message: + +| Method | Operation | +|---|---| +| `POST` | Add record | +| `PUT` | Update record | +| `DELETE` | Delete record | + +``` +POST https://{environment}.rest.afas.online/ProfitRestServices/connectors/FiEntries +``` + +The OpenAPI specification of an endpoint shows which methods it supports. + +#### POST + +With `POST`, you create records in Profit. Before the record is created, the data is validated. Examples of these validations are: + +- BSN: the citizen service number (BSN) must pass the 11-test. +- Address: the address must contain a country code. +- Financial entry: the entry must be balanced. This means the debit and credit totals must be equal. + +> If you receive an HTTP 500 response, the content of the request did not pass validation. See also [Troubleshooting](./troubleshooting). + +**Example POST request** + +```javascript const url = "https://12345.rest.afas.online/ProfitRestServices/connectors/KnUser"; const headers = new Headers(); headers.append("Accept", "application/json"); headers.append("Accept-Language", "nl-nl"); -headers.append("Authorization", "AfasToken PHRva2VuPjx2ZXJzaW9uPjE8L3ZlcnNpb04+PGRhdGE+QURFMzcwQkU4REFGNDBEMEExN0ZGQjkxNEU0MjY3NUU5OTk4QzJENTQ2QTJGNEZBM0U0RjNBQkZBODY3Qjk2RjwvZGF0YT48L3Rva2VuPg=="); +headers.append("Authorization", "Bearer {token}"); headers.append("Content-Type", "application/json"); const data = JSON.stringify({ @@ -53,78 +151,99 @@ fetch(url, requestOptions) .catch(error => console.log('Error:', error)); ``` -## Response +#### PUT -UpdateConnectors usually give an `HTTP 201 response` when they work successfully. You can find this response in the OpenAPI Specification of the endpoint. The `FieldId` in the response body is the `primary key` of the object where the POST was done. +With `PUT`, you update existing records. In the JSON schema of the `PUT` method, only the key fields are required. These are usually the fields you get back in the response of a `POST`. -Example: +A `PUT` request updates all fields you send, and all subobjects whose key you send. -```json -{ - "results": { - "KnSubject": { - "SbId": "999999" - } - } -} +**Clearing a field** + +You clear a field by sending an empty value. For example, if the field `Ds` contains `Example description`, you clear it with `"Ds": ""`. + +#### DELETE + +Not all endpoints support `DELETE`. A delete is **permanent**: afterwards, the record no longer exists in the database. You pass the key of the record as parameters in the URL. + +``` +DELETE https://12345.rest.afas.online/ProfitRestServices/connectors/KnAppointment/KnAppointment/ApId/123 ``` -See also: +This deletes the record whose `ApId` field has the value `123`. -- [All response codes](./troubleshooting#http-codes) +**Deleting a nested line** + +You can also delete a line from a subobject. To do this, include the full key of the main object and of the subobject in the request URL. -## POST on SubObject +### 2. Addressing a subobject directly -AFAS Profit can update the main object and add to the subobject for UpdateConnectors with a nested structure. This lets you add an item to an existing sales order, for example. There are two ways to do this: +You can address a subobject directly by adding its name to the URL. With a `POST` on that URL, you add the subobject to an existing record. The main object is only used to determine which existing record the subobject belongs to. This lets you add an item to an existing sales order, for example. - 1. Use @Action tags in the request body. - 2. Specify the subobject in the request URL. +- Main object URL: `../ProfitRestServices/connectors/KnOrganisation` +- Subobject URL: `../ProfitRestServices/connectors/KnOrganisation/KnBankAccount` -**@action tag method** -You add `@Action` in the JSON object within the Fields tag. It is an extra property of the "Fields" object. Using the `@Action` tag gives you flexibility when working with complex JSON structures. These can have multiple nested subjects that need different actions. The complete body is checked and then processed as one transaction. We often see this used in: +```bash +curl -X POST "https://{environment}.rest.afas.online/ProfitRestServices/connectors/KnOrganisation/KnBankAccount" \ + -H "Content-Type: application/json" \ + -H "Accept: application/json" \ + -H "Accept-language: nl-nl" \ + -H "Authorization: Bearer {token}" \ + -d @bankaccount.json +``` -- Employee-related endpoints like `KnEmployee` and `KnEmployeeGuid`. -- Order and production-related endpoints like `FbDeliveryNote`, `FbAssembly`, and `FbSales`. +With `POST`, this adds a bank account to an existing organisation. A subobject URL only supports adding. To update an existing bank account, use `PUT` on `/connectors/KnOrganisation` and include the key fields of the organisation and the bank account. Deleting is done through the `DELETE` route with the key in the URL (see [DELETE](#delete)). The OpenAPI specification shows which routes and key fields an endpoint has. -These are endpoints with a nested structure that can go up to 6 levels deep. -Allowed values for `@Action`: +Keep the following in mind: -- insert -- update -- delete +- You address one subobject per call. If the main object has multiple subobjects, you choose in the URL which subobject you add. +- Within that subobject, you can send multiple records. +- You can also send more deeply nested objects under the subobject. Whether these are created differs per connector. Give them `"@Action": "insert"` if they must be created (see Elements without `@Action` below). +- You can update the main object at the same time, but you don't have to. -Example: turn off one salary account and add a new salary account for an employee: +In the message, include the key fields of the main object, so that Profit knows which record the subobject belongs to: -``` json +```json { - "AfasEmployee": { + "KnOrganisation": { "Element": { - "@EmId": "1234568774", "Fields": { - "@Action": "update" + "": "" }, + "Objects": { + "KnBankAccount": { + "Element": { + "Fields": { + "": "" + } + } + } + } + } + } +} +``` + +**Example:** adding multiple mileage registrations to endpoint `HrMobility` with `POST ../connectors/HrMobility/HrEmployeeMobilityRegistration`. + +```json +{ + "HrMobility": { + "Element": { + "@CcSn": 123455, "Objects": [ { - "AfasBankInfo": { + "HrEmployeeMobilityRegistration": { "Element": [ { - "@AcId": "NL57RABO0312000111", - "@NoBk": false, "Fields": { - "@Action": "update", - "SeNo": 3, - "SaAc": false, - "Iban": "NL57RABO0312000111" + "DaEn": "2023-12-01", + "KmEn": 12400 } }, { - "@AcId": "NL40BOTK0755026802", - "@NoBk": false, "Fields": { - "@Action": "insert", - "SaAc": true, - "IbCk": true, - "Iban": "NL40BOTK0755026802" + "DaEn": "2023-12-14", + "KmEn": 12910 } } ] @@ -136,37 +255,115 @@ Example: turn off one salary account and add a new salary account for an employe } ``` -> The @ symbol shows which fields are special keys or actions. +### 3. Operation per element with `@Action` + +With the `@Action` attribute in `Fields`, you specify per record which operation must be performed. This overrides the default operation of the HTTP method for that element. + +| Value | Operation | +|---|---| +| `insert` | Add record | +| `update` | Update record | +| `delete` | Delete record | -**Subobject via URL method** -You can create new subobjects with a POST request to the subobject URL. This can also update the main object. You can include deeper nested objects too. +The value is not case-sensitive: `Insert` also works. -In the URL, choose which subobject to create. If there are multiple subobjects, pick the one you want. You can include multiple items in the object. +This lets you combine different operations in one message. The complete body is validated first and then processed as one transaction. You mainly use `@Action` with endpoints that have a deeply nested structure (sometimes up to six levels), for example: -- Main object URL: `../ProfitRestServices/connectors/HrMobility` -- Subobject URL: `../ProfitRestServices/connectors/HrMobility/HrEmployeeMobilityRegistration` +- Employees: `KnEmployee` and `KnEmployeeGuid`. +- Orders and production: `FbDeliveryNote`, `FbAssembly` and `FbSales`. -Example of multiple mileage registrations on the HrMobility endpoint: +In the following example, an existing assembly order, an order line and a component line are updated. A new batch line is added under the component line. -``` json +```json { - "HrMobility": { + "FbAssembly": { "Element": { - "@CcSn": 123455, + "Fields": { + "@Action": "update", + "OrNu": "00011" + }, + "Objects": { + "FbAssemblyLines": { + "Element": { + "Fields": { + "@Action": "update", + "VaIt": "7", + "ItCd": "S10000" + }, + "Objects": { + "AfasFbOrderCompLines": { + "Element": { + "Fields": { + "@Action": "update", + "VaIt": "2", + "ItCd": "3101", + "QuUn": "-2", + "BiUn": "STK" + }, + "Objects": { + "FbOrderBatchLines": { + "Element": { + "Fields": { + "@Action": "insert", + "BaNu": "10", + "BiUn": "STK", + "QuUn": "-2" + } + } + } + } + } + } + } + } + } + } + } + } +} +``` + +Schematically: + +``` +FbAssembly update assembly order 00011 +└ FbAssemblyLines update order line S10000 + └ AfasFbOrderCompLines update component line 3101 + └ FbOrderBatchLines insert new batch line 10 +``` + +**Example:** deactivating an employee's salary account and adding a new salary account in one request. + +```json +{ + "AfasEmployee": { + "Element": { + "@EmId": "1234568774", + "Fields": { + "@Action": "update" + }, "Objects": [ { - "HrEmployeeMobilityRegistration": { + "AfasBankInfo": { "Element": [ { + "@AcId": "NL57RABO0312000111", + "@NoBk": false, "Fields": { - "DaEn": "2023-12-01", - "KmEn": 12400 + "@Action": "update", + "SeNo": 3, + "SaAc": false, + "Iban": "NL57RABO0312000111" } }, { + "@AcId": "NL40BOTK0755026802", + "@NoBk": false, "Fields": { - "DaEn": "2023-12-14", - "KmEn": 12910 + "@Action": "insert", + "SaAc": true, + "IbCk": true, + "Iban": "NL40BOTK0755026802" } } ] @@ -178,24 +375,70 @@ Example of multiple mileage registrations on the HrMobility endpoint: } ``` -## PUT +#### Elements without `@Action` + +An element without `@Action` gets the operation of the HTTP method. The operation is not inherited from the parent element: each element is evaluated separately. + +**Example:** you send a `PUT` and give a person `"@Action": "insert"`. A subobject of that person without its own `@Action` is still processed as an update. -Each endpoint shows which actions you can use in the Open API specification. For `PUT` actions, only the key fields are required. This is usually the same as the `POST` action result. Use the JSON schema of the endpoint method for this. +Do you call the connector with a subobject in the URL, for example `/connectors/FbAssembly/FbAssemblyLines`? Then only the objects whose name is in the URL get the operation of the HTTP method. All other elements without `@Action` get the update operation. This applies to the main element and also to objects nested more deeply under the subobject. -A `PUT` request always updates all fields in the request and all subobjects with their key included. +What happens to those elements next differs per connector: -### Clearing a field +- The main element is updated, so it must refer to an existing record. +- Some connectors still create deeply nested objects under a new element. With `FbAssembly`, for example, batch and serial lines under a new assembly line are always created. +- If the parent element is updated, a deeply nested object without `@Action` is also processed as an update. -To clear a field, give it an empty value. For example, if field `Ds` has `Example description`, you can clear it with `"Ds": ""`. +To create a deeply nested object under an element that is being updated, give it `"@Action": "insert"`. You can see this in the `FbAssembly` example above: the new batch line sits under an existing component line. If you are not sure how a connector behaves, give the object `"@Action": "insert"` as well. -## DELETE +#### Pitfalls -Some endpoints can use the `DELETE` method. This is a FINAL delete. After this, the data no longer exists in the database. You delete data by including the data key as URL parameters. +- **Put `@Action` in `Fields`, not on `Element`.** + In `"Element": { "@Action": "insert", "Fields": { ... } }`, `@Action` is ignored without an error message. The element then gets the operation of the HTTP method. +- **Write `@Action` with a capital A.** + `"@action"` in lowercase is overridden by the operation of the HTTP method without an error message. Only the value is not case-sensitive. +- **Put `@Action` first in `Fields`.** + Only the first attribute in `Fields` is read as the operation. If you put another `@` field before it, for example a key field as an attribute, you get the error `Invalid action ''. Only 'insert', 'delete' and 'update' are supported.` +- **Give each level of nested objects its own `@Action`.** + If a subobject needs a different operation than the HTTP method, give it its own `@Action`. An `@Action` on the parent element does not count. -Example URL with parameters: `https://12345.rest.afas.online/ProfitRestServices/connectors/KnAppointment/KnAppointment/ApId/123` +## Key fields -In this case, the row with ID `123` is deleted based on the field `ApId`. +When updating or deleting, Profit must be able to find the existing record. That is why you always include the key fields of the record, even if you don't change them. Which fields make up the key differs per object. -### Deleting a nested row +## Response + +A successful call to an UpdateConnector usually returns an `HTTP 201` response. The exact response of an endpoint is listed in the OpenAPI specification of that endpoint. After a `POST`, the response body contains the primary key of the created record. -You can delete a row from a subelement. Do this by including the full key of the main element and the subelement in the request URL. \ No newline at end of file +Example: + +```json +{ + "results": { + "KnSubject": { + "SbId": "999999" + } + } +} +``` + +See also: + +- [All response codes](./troubleshooting#http-codes) + +## SOAP + +With SOAP, you send the same message in XML format. There is no HTTP method, so you specify the operation with the `Action` attribute on `Fields`: + +```xml + + + + 00011 + + + ... + + + +``` diff --git a/markdownpages/profit/nl/update-connector.md b/markdownpages/profit/nl/update-connector.md index da00275..f24da2a 100644 --- a/markdownpages/profit/nl/update-connector.md +++ b/markdownpages/profit/nl/update-connector.md @@ -1,31 +1,127 @@ --- author: CLN -date: 2025-11-08 +date: 2026-11-17 tags: UpdateConnector, Authorization, Hr, Order Management title: UpdateConnector --- -Een externe applicatie kan records in de Profit-database toevoegen, wijzigen of verwijderen via een UpdateConnector (de mogelijkheden verschillen per endpoint). In UpdateConnectoren met subobjecten is het mogelijk om een specifieke actie op een subobject mee te geven. +Met een UpdateConnector schrijf je gegevens naar Profit: je voegt records toe, werkt ze bij of verwijdert ze. Welke bewerkingen mogelijk zijn, verschilt per endpoint. Op deze pagina lees je hoe een bericht is opgebouwd en hoe je bepaalt welke bewerking (toevoegen, bijwerken of verwijderen) wordt uitgevoerd. -## POST +## Opbouw van een bericht -Via HTTP method POST maak je met een UpdateConnector records aan in Profit. Voordat het record wordt aangemaakt wordt deze data gevalideerd. Voorbeelden van deze validaties zijn: +Een UpdateConnector-bericht is hiërarchisch opgebouwd. Elk niveau bestaat uit dezelfde bouwstenen: -- BSN: het BSN (Burgerservicenummer) moet aan de 11-proef voldoen. +| Onderdeel | Betekenis | +|---|---| +| Objectnaam (bijv. `FiEntryPar`) | Het object dat je aanspreekt. Op het hoogste niveau is dit het hoofdobject van de connector. De naam daarvan kan afwijken van de connectornaam in de URL: connector `FiEntries` heeft bijvoorbeeld hoofdobject `FiEntryPar`. | +| `Element` | Eén record. Gebruik een array (`[ ... ]`) om meerdere records van hetzelfde type mee te sturen. | +| `Fields` | De veldwaarden van het record. | +| `Objects` | Onderliggende objecten (subobjecten) die bij dit record horen. Elk subobject heeft weer dezelfde opbouw. | + +**Voorbeeld:** een journaalpost met drie boekingsregels. + +```json +{ + "FiEntryPar": { + "Element": { + "Fields": { + "Year": "2026", + "Peri": "1", + "UnId": "1", + "JoCo": "20", + "AuNu": "1" + }, + "Objects": { + "FiEntries": { + "Element": [ + { + "Fields": { + "VaAs": "2", + "AcNr": "10001", + "EnDa": "2026-01-01", + "BpDa": "2026-01-01", + "AmDe": "12100", + "AmCr": "0", + "DaEx": "2026-02-01" + } + }, + { + "Fields": { + "VaAs": "1", + "AcNr": "8010", + "EnDa": "2026-01-01", + "BpDa": "2026-01-01", + "AmDe": "0", + "AmCr": "10000", + "VaId": "1" + } + }, + { + "Fields": { + "VaAs": "1", + "AcNr": "1510", + "EnDa": "2026-01-01", + "BpDa": "2026-01-01", + "AmDe": "0", + "AmCr": "2100", + "VaId": "1" + } + } + ] + } + } + } + } +} +``` + +De kop van de journaalpost staat in `FiEntryPar`. De boekingsregels zijn subobjecten (`FiEntries`) en worden als array meegestuurd. Hoofdrecord en regels worden in één aanroep toegevoegd. + +## De bewerking bepalen + +Er zijn drie manieren om te bepalen welke bewerking Profit uitvoert. Ze lopen van eenvoudig naar flexibel. + +| Manier | De bewerking geldt voor | Gebruik je als | +|---|---|---| +| 1. HTTP-methode op de connector | Het hele bericht | je alles toevoegt, bijwerkt of verwijdert | +| 2. `POST` op een subobject | Eén onderliggend object | je alleen een subobject wilt toevoegen aan een bestaand record | +| 3. `@Action` per element | Elk afzonderlijk record | je verschillende bewerkingen in één bericht wilt combineren | + +### 1. HTTP-methode op de connector + +De HTTP-methode bepaalt de standaardbewerking voor het bericht: + +| Methode | Bewerking | +|---|---| +| `POST` | Record toevoegen | +| `PUT` | Record bijwerken | +| `DELETE` | Record verwijderen | + +``` +POST https://{omgeving}.rest.afas.online/ProfitRestServices/connectors/FiEntries +``` + +Welke methoden een endpoint ondersteunt, zie je in de OpenAPI-specificatie van dat endpoint. + +#### POST + +Met `POST` maak je records aan in Profit. Voordat het record wordt aangemaakt, worden de gegevens gevalideerd. Voorbeelden van deze validaties zijn: + +- BSN: het burgerservicenummer (BSN) moet aan de 11-proef voldoen. - Adres: het adres moet een landcode bevatten. -- Financiële mutatie: een financiële mutatie moet in balans zijn. Dit betekent dat de debet- en credittotalen gelijk zijn. +- Financiële mutatie: de mutatie moet in balans zijn. De debet- en credittotalen moeten dus gelijk zijn. -> HTTP 500 response betekent dat de inhoud van de request niet succesvol gevalideerd kan worden. Zie ook [Fouten verhelpen](./troubleshooting). +> Krijg je een HTTP 500-response, dan is de inhoud van de request niet door de validatie gekomen. Zie ook [Fouten verhelpen](./troubleshooting). -### Voorbeeld POST-request +**Voorbeeld POST-request** -``` javascript +```javascript const url = "https://12345.rest.afas.online/ProfitRestServices/connectors/KnUser"; const headers = new Headers(); headers.append("Accept", "application/json"); headers.append("Accept-Language", "nl-nl"); -headers.append("Authorization", "AfasToken PHRva2VuPjx2ZXJzaW9uPjE8L3ZlcnNpb04+PGRhdGE+QURFMzcwQkU4REFGNDBEMEExN0ZGQjkxNEU0MjY3NUU5OTk4QzJENTQ2QTJGNEZBM0U0RjNBQkZBODY3Qjk2RjwvZGF0YT48L3Rva2VuPg=="); +headers.append("Authorization", "Bearer {token}"); headers.append("Content-Type", "application/json"); const data = JSON.stringify({ @@ -55,78 +151,99 @@ fetch(url, requestOptions) .catch(error => console.log('Error:', error)); ``` -## Response +#### PUT -UpdateConnectoren geven meestal een `HTTP 201 response` als zij succesvol zijn uitgevoerd. Deze response vind je terug bij de OpenAPI Specificatie van het endpoint. Het `FieldId` dat in de response-body zit, is de `primary key` van het object waar de POST op uitgevoerd is. +Met `PUT` werk je bestaande records bij. In het JSON-schema van de `PUT`-methode zijn alleen de sleutelvelden verplicht. Dat zijn meestal de velden die je terugkrijgt in de response van een `POST`. -Voorbeeld: +Een `PUT`-request werkt alle velden bij die je meestuurt, en alle subobjecten waarvan je de sleutel meestuurt. + +**Veld leegmaken** + +Je maakt een veld leeg door een lege waarde mee te sturen. Is het veld `Ds` bijvoorbeeld gevuld met `Voorbeeld omschrijving`, dan maak je het leeg met `"Ds": ""`. + +#### DELETE + +Niet alle endpoints ondersteunen `DELETE`. Een delete is **definitief**: daarna bestaat het record niet meer in de database. Je geeft de sleutel van het record mee als parameters in de URL. -``` json -{ - "results": { - "KnSubject": { - "SbId": "999999" - } - } -} +``` +DELETE https://12345.rest.afas.online/ProfitRestServices/connectors/KnAppointment/KnAppointment/ApId/123 ``` -Zie ook: +Hier wordt het record verwijderd waarvan het veld `ApId` de waarde `123` heeft. -- [Alle response-codes](./troubleshooting#http-codes) +**Geneste regel verwijderen** -## POST op SubObject +Je kunt ook een regel uit een subobject verwijderen. Neem daarvoor de volledige sleutel van het hoofdobject en van het subobject op in de request-URL. -AFAS Profit biedt de mogelijkheid op UpdateConnectoren met een geneste structuur een update op het main object te doen en een insert op het subobject. Hiermee kan je bijvoorbeeld een artikel toevoegen aan een bestaande verkooporder. Hiervoor zijn twee methoden beschikbaar: +### 2. Een subobject direct aanspreken - 1. @Action tags meegeven in de request body. - 2. Het subobject specificeren in de request URL. +Je kunt een subobject direct aanspreken door de naam ervan aan de URL toe te voegen. Met een `POST` op die URL voeg je het subobject toe aan een bestaand record. Het hoofdobject wordt alleen gebruikt om te bepalen bij welk bestaand record het subobject hoort. Zo voeg je bijvoorbeeld een artikel toe aan een bestaande verkooporder. -**Methode @action tag** -`@Action` geef je in het JSON-object mee binnen de Fields-tag. Het is een additionele property van het object "Fields". Het gebruik van de `@Action` tag geeft flexibiliteit in het werken met complexe JSON-structuren waarin meerdere subjecten genest zijn en verschillende acties nodig zijn. Ook wordt de volledige body gevalideerd en wordt daarna als één transactie verwerkt. In een aantal situaties zien we deze toepassing vaak terugkomen: +- URL hoofdobject: `../ProfitRestServices/connectors/KnOrganisation` +- URL subobject: `../ProfitRestServices/connectors/KnOrganisation/KnBankAccount` + +```bash +curl -X POST "https://{omgeving}.rest.afas.online/ProfitRestServices/connectors/KnOrganisation/KnBankAccount" \ + -H "Content-Type: application/json" \ + -H "Accept: application/json" \ + -H "Accept-language: nl-nl" \ + -H "Authorization: Bearer {token}" \ + -d @bankrekening.json +``` -- Medewerker gerelateerde endpoints zoals `KnEmployee` en `KnEmployeeGuid`. -- Order en productie gerelateerde endpoints zoals `FbDeliveryNote`, `FbAssembly` en `FbSales`. +Met `POST` voeg je zo een bankrekening toe aan een bestaande organisatie. Een subobject-URL ondersteunt alleen toevoegen. Wil je een bestaande bankrekening bijwerken, gebruik dan `PUT` op `/connectors/KnOrganisation` en neem de sleutelvelden van de organisatie en de bankrekening op. Verwijderen gaat via de `DELETE`-route met de sleutel in de URL (zie [DELETE](#delete)). Welke routes en sleutelvelden een endpoint heeft, staat in de OpenAPI-specificatie. -Dit zijn endpoints met een geneste structuur die soms tot 6 nesting-niveau's diep kan gaan. -Toegestane waarden voor `@Action`: +Houd hierbij rekening met het volgende: -- insert -- update -- delete +- Je spreekt per aanroep één subobject aan. Heeft het hoofdobject meerdere subobjecten, dan kies je in de URL welk subobject je toevoegt. +- Binnen dat subobject kun je wel meerdere records meesturen. +- Je kunt ook dieper geneste objecten onder het subobject meesturen. Of die worden aangemaakt, verschilt per connector. Geef ze `"@Action": "insert"` als ze zeker moeten worden aangemaakt (zie Elementen zonder `@Action` hieronder). +- Je kunt tegelijk het hoofdobject bijwerken, maar dat hoeft niet. -Voorbeeld deactiveren van salarisrekening en aanmaken nieuwe salarisrekening op een medewerker in 1 request: +In het bericht neem je de sleutelvelden van het hoofdobject op, zodat Profit weet bij welk record het subobject hoort: -``` json +```json { - "AfasEmployee": { + "KnOrganisation": { "Element": { - "@EmId": "1234568774", "Fields": { - "@Action": "update" + "": "" }, + "Objects": { + "KnBankAccount": { + "Element": { + "Fields": { + "": "" + } + } + } + } + } + } +} +``` + +**Voorbeeld:** meerdere kilometerregistraties toevoegen bij endpoint `HrMobility` met `POST ../connectors/HrMobility/HrEmployeeMobilityRegistration`. + +```json +{ + "HrMobility": { + "Element": { + "@CcSn": 123455, "Objects": [ { - "AfasBankInfo": { + "HrEmployeeMobilityRegistration": { "Element": [ { - "@AcId": "NL57RABO0312000111", - "@NoBk": false, "Fields": { - "@Action": "update", - "SeNo": 3, - "SaAc": false, - "Iban": "NL57RABO0312000111" + "DaEn": "2023-12-01", + "KmEn": 12400 } }, { - "@AcId": "NL40BOTK0755026802", - "@NoBk": false, "Fields": { - "@Action": "insert", - "SaAc": true, - "IbCk": true, - "Iban": "NL40BOTK0755026802" + "DaEn": "2023-12-14", + "KmEn": 12910 } } ] @@ -138,37 +255,115 @@ Voorbeeld deactiveren van salarisrekening en aanmaken nieuwe salarisrekening op } ``` -> Het @ symbool in geeft hier aan welke velden als actie op het object of als primarykey worden verwerkt. +### 3. Bewerking per element met `@Action` + +Met het attribuut `@Action` in `Fields` geef je per record aan welke bewerking moet plaatsvinden. Daarmee overschrijf je voor dat element de standaardbewerking van de HTTP-methode. -**Methode subobject via URL** -Via een POST op een subobject maak je eenvoudig een nieuw subobject aan. Hierbij is het optioneel om het hoofdobject te updaten. Ook kun je dieper geneste objecten meegeven. Deze zullen aangemaakt worden. +| Waarde | Bewerking | +|---|---| +| `insert` | Record toevoegen | +| `update` | Record bijwerken | +| `delete` | Record verwijderen | -In de URL specificeer je de actie op het subobject. Als er meerdere subobjecten beschikbaar zijn moet je hierin een keuze maken welk object je aanmaakt. Wel kan je meerdere items in het object meegeven. +Hoofdletters maken bij de waarde niet uit: `Insert` werkt ook. -- URL mainobject: ``` ../ProfitRestServices/connectors/HrMobility ``` -- URL subobject: ``` ../ProfitRestServices/connectors/HrMobility/HrEmployeeMobilityRegistration ``` +Zo combineer je verschillende bewerkingen in één bericht. De volledige body wordt eerst gevalideerd en daarna als één transactie verwerkt. Je gebruikt `@Action` vooral bij endpoints met een diep geneste structuur (soms tot zes niveaus), bijvoorbeeld: -Voorbeeld meerdere kilometerregistraties op endpoint HrMobility: +- Medewerkers: `KnEmployee` en `KnEmployeeGuid`. +- Orders en productie: `FbDeliveryNote`, `FbAssembly` en `FbSales`. -``` json +In het volgende voorbeeld worden een bestaande assemblageorder, een orderregel en een componentregel bijgewerkt. Onder de componentregel wordt een nieuwe batchregel toegevoegd. + +```json { - "HrMobility": { + "FbAssembly": { "Element": { - "@CcSn": 123455, + "Fields": { + "@Action": "update", + "OrNu": "00011" + }, + "Objects": { + "FbAssemblyLines": { + "Element": { + "Fields": { + "@Action": "update", + "VaIt": "7", + "ItCd": "S10000" + }, + "Objects": { + "AfasFbOrderCompLines": { + "Element": { + "Fields": { + "@Action": "update", + "VaIt": "2", + "ItCd": "3101", + "QuUn": "-2", + "BiUn": "STK" + }, + "Objects": { + "FbOrderBatchLines": { + "Element": { + "Fields": { + "@Action": "insert", + "BaNu": "10", + "BiUn": "STK", + "QuUn": "-2" + } + } + } + } + } + } + } + } + } + } + } + } +} +``` + +Schematisch: + +``` +FbAssembly update assemblageorder 00011 +└ FbAssemblyLines update orderregel S10000 + └ AfasFbOrderCompLines update componentregel 3101 + └ FbOrderBatchLines insert nieuwe batchregel 10 +``` + +**Voorbeeld:** een salarisrekening van een medewerker deactiveren en een nieuwe salarisrekening aanmaken in één request. + +```json +{ + "AfasEmployee": { + "Element": { + "@EmId": "1234568774", + "Fields": { + "@Action": "update" + }, "Objects": [ { - "HrEmployeeMobilityRegistration": { + "AfasBankInfo": { "Element": [ { + "@AcId": "NL57RABO0312000111", + "@NoBk": false, "Fields": { - "DaEn": "2023-12-01", - "KmEn": 12400 + "@Action": "update", + "SeNo": 3, + "SaAc": false, + "Iban": "NL57RABO0312000111" } }, { + "@AcId": "NL40BOTK0755026802", + "@NoBk": false, "Fields": { - "DaEn": "2023-12-14", - "KmEn": 12910 + "@Action": "insert", + "SaAc": true, + "IbCk": true, + "Iban": "NL40BOTK0755026802" } } ] @@ -180,24 +375,70 @@ Voorbeeld meerdere kilometerregistraties op endpoint HrMobility: } ``` -## PUT +#### Elementen zonder `@Action` + +Een element zonder `@Action` krijgt de bewerking van de HTTP-methode. De bewerking wordt niet overgenomen van het bovenliggende element: elk element wordt los beoordeeld. + +**Voorbeeld:** je doet een `PUT` en geeft een persoon `"@Action": "insert"`. Een subobject van die persoon zonder eigen `@Action` wordt dan toch als update verwerkt. -Per endpoint wordt aangegeven in de Open API specificatie welke acties zijn toegestaan. Bij het schema van de `PUT` actie op een endpoint zijn alleen de sleutelvelden verplichte velden. Dit is meestal hetzelfde als het resultaat van het `POST` actie. Gebruik hiervoor het JSON schema van de method van het endpoint. +Roep je de connector aan met een subobject in de URL, bijvoorbeeld `/connectors/FbAssembly/FbAssemblyLines`? Dan krijgen alleen de objecten waarvan de naam in de URL staat de bewerking van de HTTP-methode. Alle andere elementen zonder `@Action` krijgen de bewerking update mee. Dat geldt voor het hoofdelement en ook voor objecten die dieper onder het subobject hangen. -Een `PUT` request update altijd alle velden die worden meegegeven in de request en alle subobjecten waarvan de sleutel meegegeven is. +Wat er daarna met die elementen gebeurt, verschilt per connector: -### Veld leegmaken +- Het hoofdelement wordt bijgewerkt. Het moet dus een bestaand record aanwijzen. +- Sommige connectoren maken dieper geneste objecten onder een nieuw element toch aan. Bij `FbAssembly` worden batch- en serieregels onder een nieuwe assemblageregel bijvoorbeeld altijd aangemaakt. +- Wordt het bovenliggende element bijgewerkt, dan wordt een dieper genest object zonder `@Action` ook als update verwerkt. -Door een lege waarde mee te geven wordt het veld leeg gemaakt. Bijvoorbeeld: als veld `Ds` gevuld is met `Voorbeeld omgeschrijving` maak je deze leeg met `"Ds": ""`. +Wil je een dieper genest object aanmaken onder een element dat wordt bijgewerkt, geef het dan `"@Action": "insert"`. Dat zie je in het voorbeeld met `FbAssembly` hierboven: de nieuwe batchregel hangt onder een bestaande componentregel. Weet je niet zeker hoe een connector zich gedraagt, geef het object dan ook `"@Action": "insert"`. -## DELETE +#### Valkuilen -Een deel van de endpoints heeft de mogelijkheid om method `DELETE` uit te voeren. Dit is een DEFINITIEVE delete waarna het gegeven niet meer in de database bestaat. De delete voer je uit door de sleutel van het gegeven mee te geven als URL parameters. +- **Zet `@Action` in `Fields`, niet op `Element`.** + In `"Element": { "@Action": "insert", "Fields": { ... } }` wordt `@Action` zonder foutmelding genegeerd. Het element krijgt dan de bewerking van de HTTP-methode. +- **Schrijf `@Action` met een hoofdletter A.** + `"@action"` in kleine letters wordt zonder foutmelding overschreven door de bewerking van de HTTP-methode. Alleen bij de waarde maken hoofdletters niet uit. +- **Zet `@Action` als eerste in `Fields`.** + Alleen het eerste attribuut in `Fields` wordt als bewerking gelezen. Zet je een ander `@`-veld ervoor, bijvoorbeeld een sleutelveld als attribuut, dan krijg je de fout `Invalid action ''. Only 'insert', 'delete' and 'update' are supported.` +- **Geef bij geneste objecten elke laag een eigen `@Action`.** + Moet een subobject een andere bewerking krijgen dan de HTTP-methode, geef het dan zelf een `@Action`. Een `@Action` op het bovenliggende element telt niet mee. -Voorbeeld URL met parameters: `https://12345.rest.afas.online/ProfitRestServices/connectors/KnAppointment/KnAppointment/ApId/123` +## Sleutelvelden -Hier wordt op basis het veld `ApId` regel met identifier `123` verwijderd. +Bij bijwerken en verwijderen moet Profit het bestaande record kunnen vinden. Neem daarom altijd de sleutelvelden van het record op, ook als je die zelf niet wijzigt. Welke velden de sleutel vormen, verschilt per object. -### Geneste regel verwijderen +## Response + +Een geslaagde aanroep van een UpdateConnector geeft meestal een `HTTP 201`-response. Welke response een endpoint precies geeft, staat in de OpenAPI-specificatie van dat endpoint. Na een `POST` bevat de response-body de primary key van het aangemaakte record. + +Voorbeeld: + +```json +{ + "results": { + "KnSubject": { + "SbId": "999999" + } + } +} +``` -Het is mogelijk om een regel uit een subelement te verwijderen. Dit kan je doen door de volledige sleutel van het hoofd element en het subelement in de request URL op te nemen. \ No newline at end of file +Zie ook: + +- [Alle response-codes](./troubleshooting#http-codes) + +## SOAP + +Via SOAP verstuur je hetzelfde bericht in XML-vorm. Er is geen HTTP-methode, dus de bewerking geef je aan met het attribuut `Action` op `Fields`: + +```xml + + + + 00011 + + + ... + + + +```