From 051ecf6e22d529968deb9dbc64e009f78c109640 Mon Sep 17 00:00:00 2001 From: Eric Zwaal Date: Tue, 29 Jul 2025 16:44:23 +0200 Subject: [PATCH 1/2] Bestandsnamen en verwijzingen naar kebab-casing omgezet --- .../Endpoint/endpoint_markdown_files.json | 32 +-- .../Profit/en/app-connector-auditor-afas.md | 46 ++++ .../en/app-connector-auditor-partner.md | 208 +++++++++++++++++ .../Profit/en/app-connector-auditor.md | 123 ++++++++++ .../{Howto template.md => howto-template.md} | 0 .../Profit/nl/app-connector-auditor-afas.md | 47 ++++ .../nl/app-connector-auditor-partner.md | 213 ++++++++++++++++++ .../Profit/nl/app-connector-auditor.md | 125 ++++++++++ ...{Change tracking.md => change-tracking.md} | 0 .../en/{Howto payroll.md => howto-payroll.md} | 0 .../sb/en/{Howto pos.md => howto-pos.md} | 0 ...asejournal.md => howto-purchasejournal.md} | 0 ...{Howto relations.md => howto-relations.md} | 0 ... salesinvoice.md => howto-salesinvoice.md} | 0 ... salesjournal.md => howto-salesjournal.md} | 0 .../sb/en/{News howtos.md => news-howtos.md} | 0 .../sb/en/{News sb2.md => news-sb2.md} | 0 ...{Change tracking.md => change-tracking.md} | 0 .../nl/{Howto payroll.md => howto-payroll.md} | 0 .../sb/nl/{Howto pos.md => howto-pos.md} | 0 ...asejournal.md => howto-purchasejournal.md} | 0 ...{Howto relations.md => howto-relations.md} | 0 ... salesinvoice.md => howto-salesinvoice.md} | 0 ... salesjournal.md => howto-salesjournal.md} | 0 .../sb/nl/{News howtos.md => news-howtos.md} | 0 .../sb/nl/{News sb2.md => news-sb2.md} | 0 menustructures/multilanguage_menu.json | 62 ++--- 27 files changed, 809 insertions(+), 47 deletions(-) create mode 100644 MarkdownPages/Profit/en/app-connector-auditor-afas.md create mode 100644 MarkdownPages/Profit/en/app-connector-auditor-partner.md create mode 100644 MarkdownPages/Profit/en/app-connector-auditor.md rename MarkdownPages/Profit/{Howto template.md => howto-template.md} (100%) create mode 100644 MarkdownPages/Profit/nl/app-connector-auditor-afas.md create mode 100644 MarkdownPages/Profit/nl/app-connector-auditor-partner.md create mode 100644 MarkdownPages/Profit/nl/app-connector-auditor.md rename MarkdownPages/sb/en/{Change tracking.md => change-tracking.md} (100%) rename MarkdownPages/sb/en/{Howto payroll.md => howto-payroll.md} (100%) rename MarkdownPages/sb/en/{Howto pos.md => howto-pos.md} (100%) rename MarkdownPages/sb/en/{Howto purchasejournal.md => howto-purchasejournal.md} (100%) rename MarkdownPages/sb/en/{Howto relations.md => howto-relations.md} (100%) rename MarkdownPages/sb/en/{Howto salesinvoice.md => howto-salesinvoice.md} (100%) rename MarkdownPages/sb/en/{Howto salesjournal.md => howto-salesjournal.md} (100%) rename MarkdownPages/sb/en/{News howtos.md => news-howtos.md} (100%) rename MarkdownPages/sb/en/{News sb2.md => news-sb2.md} (100%) rename MarkdownPages/sb/nl/{Change tracking.md => change-tracking.md} (100%) rename MarkdownPages/sb/nl/{Howto payroll.md => howto-payroll.md} (100%) rename MarkdownPages/sb/nl/{Howto pos.md => howto-pos.md} (100%) rename MarkdownPages/sb/nl/{Howto purchasejournal.md => howto-purchasejournal.md} (100%) rename MarkdownPages/sb/nl/{Howto relations.md => howto-relations.md} (100%) rename MarkdownPages/sb/nl/{Howto salesinvoice.md => howto-salesinvoice.md} (100%) rename MarkdownPages/sb/nl/{Howto salesjournal.md => howto-salesjournal.md} (100%) rename MarkdownPages/sb/nl/{News howtos.md => news-howtos.md} (100%) rename MarkdownPages/sb/nl/{News sb2.md => news-sb2.md} (100%) diff --git a/MarkdownPages/Endpoint/endpoint_markdown_files.json b/MarkdownPages/Endpoint/endpoint_markdown_files.json index fb24885f..4362aeb9 100644 --- a/MarkdownPages/Endpoint/endpoint_markdown_files.json +++ b/MarkdownPages/Endpoint/endpoint_markdown_files.json @@ -1,21 +1,21 @@ [ "debtorbalance_1.0_get.md", - "FbConfrontation_post.md", - "FbDeliveryNote_post.md", - "FiEntries_delete.md", - "FiEntries_post.md", - "HrAbsenceID_put.md", - "HrAbsence_post.md", - "HrCompMut_post.md", - "HrIllnessInSite_post.md", - "HrRelative_post.md", - "KnAddress_post.md", - "KnEmployee_post.md", - "KnPerson_post.md", - "KnSubject_post.md", - "Profit_Debtor_Invoices_get.md", - "PtPriceAgreement_post.md", + "fbconfrontation_post.md", + "fbdeliverynote_post.md", + "fientries_delete.md", + "fientries_post.md", + "hrabsenceid_put.md", + "hrabsence_post.md", + "hrcompmut_post.md", + "hrillnessinsite_post.md", + "hrrelative_post.md", + "knaddress_post.md", + "knemployee_post.md", + "knperson_post.md", + "knsubject_post.md", + "profit_debtor_invoices_get.md", + "ptpriceagreement_post.md", "purchaseinvoice_1.0_post.md", "purchasejournalentry_1.0_create_post.md", - "SubjectConnector_get.md" + "subjectconnector_get.md" ] diff --git a/MarkdownPages/Profit/en/app-connector-auditor-afas.md b/MarkdownPages/Profit/en/app-connector-auditor-afas.md new file mode 100644 index 00000000..58565cc8 --- /dev/null +++ b/MarkdownPages/Profit/en/app-connector-auditor-afas.md @@ -0,0 +1,46 @@ +--- +title: Partner Integration Self Service for AFAS employees +author: Eric Zwaal +date: 2025-01-21 +tags: Appconnector, setup, GetConnector +index: false +--- + +This version of the AppConnector Auditor shows almost all points that are also shown at other levels. In addition, it contains a good dose of technical information. The purpose of this is: +1. To validate the other points +2. To have extra insight, especially in the GetConnectors + +Note that no partner information is shown in this document. + +## Additional data for Auditor for Consultancy + +Nothing at all! + +## Additional data for Auditor for AFAS PD + +### General + +The application server environment is shown, and any special settings. + +### GetConnectors + +For each GetConnector, the following information is displayed: + +#### Performance information + +Various data that provides insight into the speed of the connector. + +#### Returned field list + +Shows all fields that have ever been returned by this connector. This list is collected from the logs and gives insight into which (custom) fields are being used. + +#### Metadata + +Shows the fields present in the connector metadata. + +#### Difference between returned field list and metadata + +Shows differences between the fields that are returned and the fields in the metadata. Differences can arise when: +- Free fields are retrieved that are not present in the test environment where the GetConnector was exported +- The GetConnector is outdated and newer fields are not included in the metadata +- Fields in the metadata are no longer being used in practice diff --git a/MarkdownPages/Profit/en/app-connector-auditor-partner.md b/MarkdownPages/Profit/en/app-connector-auditor-partner.md new file mode 100644 index 00000000..adf6ecdd --- /dev/null +++ b/MarkdownPages/Profit/en/app-connector-auditor-partner.md @@ -0,0 +1,208 @@ +--- +title: AppConnector auditor for Partners +author: Eric Zwaal +date: 2025-01-21 +tags: Appconnector, setup, GetConnector +index: true +--- + +## Introduction + +Since Profit 5 (autumn 2024), we have the AppConnector Auditor: a useful tool to quickly gain insight into an AppConnector. For you as a partner, it's a tool to see to what extent your integration meets AFAS best practices (and sometimes requirements). + +## What you need + +- AFAS Environment +- An AppConnector that is set up as you would have it done at a customer +- The correct permissions: + - Authorization tool > Authorization > General > Management > App connector > Actions > AppConnector auditor + +## Using the auditor + +1. Go to the menu `General > Management > App connector` +2. Open the properties of the AppConnector you want to analyze +3. Click on `Actions` next to the row of tabs on the left side +4. Click on the action `Auditor (for partners)` +5. After a few seconds you'll get the message "Audit information has been copied to the clipboard". +6. Open a markdown editor, for example [StackEdit](https://stackedit.io/) +7. Clear the left panel and paste the clipboard content there (CTRL + V) +8. In the right panel you'll now see a report about the AppConnector + +## Explanation of the analysis + +What you see in the Auditor naturally depends on the AppConnector. In this section I'll cover which messages you might see, and what you can do with them. Due to translation being applied, text might look slightly different for you. The order may also vary. + +### Your data + +This section shows some data that we at AFAS have about you. + +- Name: The name of your company. Since invoices are also sent here, it's important that this is your official company name. +- Subscription number: The number of the subscription at AFAS under which your partner license falls. This is also the first part of the IntegrationId that you send along. +- Responsible person: The person at your company who is responsible for the integration. They are also the first point of contact from AFAS. +- Project manager at AFAS: Your contact person at AFAS regarding the integration. This will usually be a SystemIntegrator. +- PEN test status: If you have shown the results of a PEN test, we give it a score; you see that here. A Green score is valid for 3 years, an Orange score is valid for 15 months and a Red score is valid for 6 months. This is calculated from the date mentioned on the PEN test report. +- End date validity PEN test: This is the date of the last PEN test, increased by the validity period (see point above). After this date you formally no longer qualify as a partner and AFAS's notice period (12 months) will take effect. After the notice period expires, AFAS has the right to unilaterally terminate the partner contract. + +### IntegrationId + +This section shows data linked to your IntegrationId. If you market multiple integrations with AFAS, you also have multiple IntegrationIds and this section will be shown multiple times. + +- Project code: For each integration we have created a project. If you became a partner after March 2023, this project also contains your onboarding tasks. +- Description: Description of the project, but also of your place in the list of certified integrations. +- Certification status: Status +- Number of outstanding project tasks: If there are still tasks outstanding 12 months after the certification start date, AFAS will approach you for a final conversation. If you don't manage to complete all tasks, the partner contract will be terminated. +- Article code: Number of the article with which you are visible on the partner site. +- Introduction, Description, Website: the fields as you filled them in via https://partner.afas.nl/mijn-paginas. +- Blocked: "Yes" if your integration is not shown. If you don't know why that is, contact the SystemIntegrators. + +### Checklist for your certification process + +If all points have a checkmark then the certification is completed. Do you believe that a checkmark is incorrectly unchecked? Then contact your contact person ("Project manager") at AFAS. + +- [ ] Your data at AFAS is complete: See [above](#your-data) which data is still missing. +- [ ] Your PENtest is valid: This checkmark is on as long as your PENtest is valid. See [above](#your-data). +- [ ] Your integration is shown on our website: Check in the [IntegrationId](#integrationid) section whether Introduction, Description and Website are filled in. +- [ ] You have handled all project tasks: You have 12 months to complete all project tasks. See also [above](#integrationid). + +### Checklist for your integration + +This section is somewhat less black and white. Basically you have a good integration if all points have a checkmark, but that's not conclusive. If there are situations where a checkmark is incorrectly unchecked, you'll need to discuss that with your project manager at the SystemIntegrators. +Even if all points have a checkmark, AFAS may still want you to make adjustments. + +### Checklist for points you must address in your implementation document + +This list is closely related to the [Checklist for your integration](#checklist-for-your-integration). These points will be taken into account when assessing your implementation document. + +### App Connector + +In this section you see the name of the App Connector, and messages are shown that relate to the setup of the AppConnector itself. This is mainly intended for the end user. + +### UpdateConnectors + +This section provides a list of UpdateConnectors that can be called. + +### Other Connectors + +This section provides a list of other Connectors that can be called. Think of connectors for retrieving attachments. + +### GetConnectors: General + +This is an important section. First, messages are given that apply to multiple GetConnectors. Then the GetConnectors are shown one by one. + +#### Unknown fields are being used. + +There is a GetConnector (or multiple) in which a field is used that is not available in your environment. Often this is a free field. Ask your supplier which field it concerns; this may be necessary for the integration to function properly. + +#### Free fields are being used. + +Make sure you also offer these and that you pay attention to this in the implementation document. You can export free fields from your AFAS test environment and offer them as a downloadable file, together with the GetConnectors. + +#### The following authorizations are applied. + +Many GetConnectors only show data that has been allowed by the end user in the authorization filters. By mentioning in your implementation document which filters apply to your integration, the AFAS administrator can set everything up properly. + +#### Both EnSe and DvSn are used. + +In short: AFAS Profit knows 2 different numbers that indicate the employment. If you use them mixed up, you risk hard-to-trace errors. [Therefore read this article carefully](./howto-bi#employees-and-employment). Don't hesitate to discuss this during an appointment with a SystemIntegrator. + +#### Financial mutations are retrieved, but **Changed booking days** is not used. + +Do you retrieve many Financial mutations? Then also use the GetConnector `Changed booking days`. [Read this article carefully](https://help.afas.nl/help/NL/SE/App_Cnnct_View_Audit.htm#o79118). + +You might also be interested in retrieving deleted mutations. [Read this article for that](https://help.afas.nl/help/NL/SE/App_Cnnct_Deleted_Data.htm#o124753). + +#### Post-calculation is retrieved, but **Changed booking days post-calculation** is not used. + +Do you retrieve many post-calculation lines? Then also use the GetConnector `Changed booking days post-calculation`. [Read this article carefully](https://help.afas.nl/help/NL/SE/App_Cnnct_View_Audit.htm#o95619). + +You might also be interested in retrieving deleted post-calculation. [Read this article for that](https://help.afas.nl/help/NL/SE/App_Cnnct_Deleted_Data.htm#o124754). + +#### Below are the authorizations that apply and how the permissions are granted in your environment. + +This section gives the AFAS administrator insight into the setup of the authorization that affects your integration. Each customer will have set this up differently. + +### GetConnectors: Messages per GetConnector + +#### Number of fields, Optimal take + +Information about the GetConnector. The Optimal take is based on best practices and calculated as 150,000 / [Number of fields]. + +#### This is a supplied Profit GetConnector. + +Always create your own set of GetConnectors. +It's tempting to use the standard Profit GetConnectors, but the disadvantages outweigh the benefits: +- They contain fields you don't use +- You can't modify them, so if you're missing a field you still have to create your own GetConnector for that +- No filter can be applied. You can still pass a filter in the URL, but the AFAS administrator doesn't have the ability to + +#### Invalid name. This GetConnector has a name that starts with "Profit_". + +Preferably give your GetConnectors a name that starts with your company name, or the name of the app you're connecting. This prevents conflicts when a customer has multiple integrations. + +#### This GetConnector has 1 or more unknown fields. + +See [above](#unknown-fields-are-being-used). + +#### This GetConnector has 1 or more free fields. + +See [above](#free-fields-are-being-used). + +#### This GetConnector has 1 or more fields with a dot in the name. + +That can cause problems if you want to filter or sort on these fields in the URL. Adjust the name so it doesn't contain a dot. + +#### This GetConnector has fields that are marked as privacy-sensitive. + +In Profit, a set of data is marked as privacy-sensitive. In this section you see which of those fields are used in the integration. Review the list carefully; engage in conversation with the supplier if there are fields that the connected app doesn't necessarily need to function properly. + +#### This GetConnector uses aggregation. Check if that's justified. + +Aggregation is a fantastic tool to retrieve less data, or to have totals calculated. + +#### This GetConnector has fields with a special format. + +You can display a field differently in a GetConnector; for example a date/time as just a date or as a different date format. In many cases this changes the field type. That's not a problem in itself. However, if you start filtering or sorting on this modified field type, it makes the GetConnector many times slower, especially if there's a lot of data in the source table. That can add up to more than a factor of 100! + +#### The integration uses data per employment, but this GetConnector retrieves fields from Current data per employment relationship. + +Current data per employment relationship only shows data from the main employment. Since your integration retrieves data per employment elsewhere, this GetConnector might show incorrect data. This can cause hard-to-trace errors. [Therefore read this article carefully](./howto-bi#employees-and-employment). Don't hesitate to consult with a SystemIntegrator. + +#### This GetConnector retrieves fields from a table with data per employment, but nowhere in the integration is Employment number retrieved. + +If an employee has multiple employments, this can result in duplicate rows. [Read this article carefully](./howto-bi#employees-and-employment) for more information about multiple employments. Feel free to schedule a consultation with a SystemIntegrator. + +#### Field **name** or **description** is retrieved from a higher level. + +Do you retrieve a lot of data with this GetConnector? Then make it as clean as possible, with only fields from the main table. Retrieve redundant data with a separate GetConnector from the relevant table. That saves a lot of bandwidth and also execution time. + +#### This GetConnector has a (possible) circular reference. + +It appears that fields are being retrieved from a table, multiple references deep, while that table is also directly available. Check that. + +#### References are followed to a table that is also available as an alias. + +A so-called alias is in the left panel, from where you choose fields and add them to the data collection. In most cases it's best practice to retrieve fields as directly as possible from such an alias, because otherwise double JOINs are created. + +#### This GetConnector is authorized. + +Here you see which authorization filters apply to this specific GetConnector. If a certain authorization is not listed, then that authorization is not applied to the GetConnector. If you still want to withhold data, use a filter in the GetConnector itself. + +#### Indexes + +In this section you see all indexes that are on the main table. If that's a table with many rows, make sure you use these indexes as much as possible. That applies to filtering and sorting. If you don't do that, it can have a dramatic impact on the GetConnector's performance. + +Preferably use index 1; that's the clustered, unique primary key of the table. The fields in it provide a unique identification of each row. A few rules of thumb: +- Always include sorting in the URL +- Sort on as many fields of index 1 as possible, in the specified order of the fields. So if there's an index on Employee, Start date: then sort on those 2 fields in any case. +- Some fields are unfortunately not directly available. A SystemIntegrator can possibly adjust your GetConnector and add the hidden fields. +- If you filter in the GetConnector, do so as much as possible on index fields. +- Is index 1 not available or not logical for you? Then use one of the other indexes. Note, they are not always unique. + +#### Filters + +This section shows the filters that are stored in the GetConnector. Check if they apply to all customers. If not, pass a filter in the URL when calling. Or pay attention to it in your implementation document. +Because not all GetConnectors respect the filter authorization in the customer environment, it's often necessary that the customer also makes adjustments to the filter themselves. + +#### Slow filter + +This GetConnector has a filter that performs poorly. In a certified integration this is not allowed; it's not unthinkable that such a filter makes a GetConnector more than 100x slower. diff --git a/MarkdownPages/Profit/en/app-connector-auditor.md b/MarkdownPages/Profit/en/app-connector-auditor.md new file mode 100644 index 00000000..eda91e66 --- /dev/null +++ b/MarkdownPages/Profit/en/app-connector-auditor.md @@ -0,0 +1,123 @@ +--- +title: AppConnector auditor +author: Eric Zwaal +date: 2025-01-21 +tags: Appconnector, setup, GetConnector +index: true +--- + +## Introduction + +Since Profit 5 (autumn 2024), we have the AppConnector Auditor: a useful tool to quickly gain insight into an AppConnector. This is especially handy when you want to know what an external party is requesting from you. + +## What you need + +- AFAS Environment +- An AppConnector that is set up for integration with an external party +- The correct permissions: + - Authorization tool > Authorization > General > Management > App connector > Actions > AppConnector auditor + +## Using the auditor + +1. Go to the menu `General > Management > App connector` +2. Open the properties of the AppConnector you want to analyze +3. Click on `Actions` next to the row of tabs on the left side +4. Click on the action `Auditor` +5. After a few seconds you'll get the message "Audit information has been copied to the clipboard". +6. Open a markdown editor, for example [StackEdit](https://stackedit.io/) +7. Clear the left panel and paste the clipboard content there (CTRL + V) +8. In the right panel you'll now see a report about the AppConnector + +## Explanation of the analysis + +What you see in the Auditor naturally depends on the AppConnector. In this section I'll cover which messages you might see, and what you can do with them. Due to translation being applied, text might look slightly different for you. The order may also vary. + +### App Connector + +In this section you see the name of the App Connector, and messages are shown that relate to the setup of the AppConnector itself + +#### Authorization group has more than 1 user. + +In most cases you create a separate Authorization group for each AppConnector and a separate system user. + +#### No tokens have been issued. + +Without tokens, an external party cannot connect with you. Go to the "User tokens" tab, click `New` and create a token. The description is purely informational. The token looks like this: `188537B2CBF2741E5B5A1620D15F963F93159C83CC55C4652B02D1D1ABA7A6D24`. When the external party asks for the token, always give it completely. + +> WARNING: A token gives access to data from Profit and is therefore very valuable. Never put it in an unsecured email, and make sure only the external party gets it. Don't let a token lie around! + +#### More than 1 token has been issued. + +For most integrations, only one token is needed. Remove tokens that are not used to prevent misuse. Even if there are multiple tokens for one user, they still give access to your data in Profit. + +#### A token has been issued with a limited validity period. + +You specified a validity period in the AppConnector on the `General` tab and then created a token. This means the token will no longer be valid at some point. Make sure you provide a new token before the expiration date. + +#### A token has been issued that hasn't been called for more than 3 months. + +A token that hasn't been called for a long time is probably no longer being used. Yet it still gives access to your Profit environment. Remove tokens that are no longer used to prevent misuse. + +#### A token was issued more than 12 months ago. + +It's good practice to replace tokens regularly. Follow these steps: +1. Create a new token, for the same user +2. Send this token securely to the third party that handles the integration. Note: A token gives access to data from Profit and is therefore very valuable. Never put it in an unsecured email, and make sure only the external party gets it. Don't let a token lie around! +3. When the new token is being used, you can see this from the "Date last used" on the User tokens tab. +4. Remove the old token. + +#### Connector user has access to Profit Windows. + +Always create a separate AppConnector for each integration. +Create a separate authorization group for each AppConnector, on which you set up the correct permissions. +Create one system user for each AppConnector. This user does NOT need access to Profit Windows. +Don't use an employee for an AppConnector! It makes it difficult to set up authorization properly. Moreover, all authorization expires as soon as the employee leaves service. The GetConnectors may then no longer provide data. + +#### No IP address restrictions are set up. + +For extra security, set up IP restrictions. Ask the supplier from which IP address the Connectors are called. On the "IP restrictions" tab, create a new rule for that IP address with `Access` = "Allow". From now on, all other IP addresses are blocked. +During the test phase of an integration, it may be necessary to also allow the IP addresses of AFAS Connect. + +#### Calls from AFAS Connect IP addresses are allowed. + +Once the test phase of an integration is over, it's no longer necessary to access your environment from AFAS Connect. Therefore, remove the rule(s) on the "IP restrictions" tab that allow access from AFAS Connect. +These are the IP addresses `52.174.142.76` and `52.174.142.140`. + +### UpdateConnectors + +This section provides a list of UpdateConnectors that can be called. + +### Other Connectors + +This section provides a list of other Connectors that can be called. Think of connectors for retrieving attachments. + +### GetConnectors: General + +This is an important section. First, messages are given that apply to multiple GetConnectors. Then the GetConnectors are shown one by one. + +#### Unknown fields are being used. + +There is a GetConnector (or multiple) in which a field is used that is not available in your environment. Often this is a free field. Ask your supplier which field it concerns; this may be necessary for the integration to function properly. + +#### Below are the authorizations that apply and how the permissions are granted in your environment. + +Many GetConnectors respect the filter authorization you have set up in Profit. This section gives you insight into which authorization filters are used by the Token users, and which permissions have been granted. If a Token user has too many permissions, there may be a data leak. A VoIP service provider, for example, often doesn't need to know anything about field service employees, while a planning application doesn't need permissions for office employees. + +### Messages per GetConnector + +#### This GetConnector has fields that are marked as privacy-sensitive. + +In Profit, a set of data is marked as privacy-sensitive. In this section you see which of those fields are used in the integration. Review the list carefully; engage in conversation with the supplier if there are fields that the connected app doesn't necessarily need to function properly. + +#### This GetConnector is authorized. + +Here you see which authorization filters apply to this specific GetConnector. If a certain authorization is not listed, then that authorization is not applied to the GetConnector. If you still want to withhold data, use a filter in the GetConnector itself. + +#### Filters + +This section shows the filters that are stored in the GetConnector. This is often already done by the supplier. Check if the filters are logical. +Because not all GetConnectors respect the filter authorization in the customer environment, it's often necessary that you also make adjustments to the filter yourself. + +#### Slow filter + +This GetConnector has a filter that performs poorly. Adjust this if possible, possibly in consultation with your supplier. diff --git a/MarkdownPages/Profit/Howto template.md b/MarkdownPages/Profit/howto-template.md similarity index 100% rename from MarkdownPages/Profit/Howto template.md rename to MarkdownPages/Profit/howto-template.md diff --git a/MarkdownPages/Profit/nl/app-connector-auditor-afas.md b/MarkdownPages/Profit/nl/app-connector-auditor-afas.md new file mode 100644 index 00000000..116c0d90 --- /dev/null +++ b/MarkdownPages/Profit/nl/app-connector-auditor-afas.md @@ -0,0 +1,47 @@ +--- +title: Partner Integration Self Service voor AFAS medewerkers +author: Eric Zwaal +date: 2025-01-21 +tags: Appconnector, inrichting, GetConnector +index: false +--- + +Deze versie van de AppConnector Auditor toont vrijwel alle punten die ook op andere niveaus getoond worden. Daarnaast bevat het een flinke dosis technische informatie. Doel daarvan is: +1. Om de overige punten te valideren +2. Om extra inzicht te hebben, met name in de GetConnectoren + +Let op dat er in dit document geen partner-informatie wordt getoond. + +## Extra gegevens bij Auditor voor Consultancy + +Helemaal niets! + +## Extra gegevens bij Auditor voor AFAS PD + +#### GetConnector gebruikt mogelijk een Subselect. + +In het SQL script is na de CREATE VIEW meer dan één SELECT gevonden. In sommige gevallen komt het omdat een bepaald functieveld een subselect gebruikt. Als dat in een GetConnector zit die vaak wordt aangeroepen of die veel data oplevert, kan zo'n subselect nadelig zijn voor de performance. +Controleer in het SQL script of het mogelijk is om de GetConnector zodanig aan te passen dat de subselect niet meer gebruikt wordt. + +#### Deze GetConnector haalt ook velden op vanuit een andere alias. + +Soms zijn er aliassen die ervoor zorgen dat regels uit de hoofdalias vermenigvuldigd worden. Denk aan verzuimverloopregels bij verzuimmeldingen. De indexen die in het document genoemd worden, zijn dan niet voldoende om de regels uniek te identificeren. +Controleer dit in het SQL script. + +#### Velden + +Een lijst met alle velden. Lekker handig toch!? + +#### Alle beschikbare aliassen + +Een lijst met alle beschikbare aliassen. Het kan zijn dat sommige verborgen zijn en daarom in de praktijk niet gebruikt kunnen worden. +Als een tabel beschikbaar is als alias, is het bijna altijd beter om een veld direct uit de alias te halen, in plaats van een verwijzing via de plusjes te volgen. + +#### Fk paden + +Deze tabel geeft inzicht in de fk-paden die gebruikt worden, en dus in de JOINs die daarvoor nodig zijn. Het is een tabel die intern gebruikt wordt om bijvoorbeeld de cyclische verwijzingen op te sporen. +Gebruik deze tabel om te controleren of die meldingen terecht zijn. + +#### SQL statement + +Ach, wat wil je nog meer! Het hele SQL statement, in volle glorie. Bij een meegeleverde Profit-connector is deze niet beschikbaar. diff --git a/MarkdownPages/Profit/nl/app-connector-auditor-partner.md b/MarkdownPages/Profit/nl/app-connector-auditor-partner.md new file mode 100644 index 00000000..539f5759 --- /dev/null +++ b/MarkdownPages/Profit/nl/app-connector-auditor-partner.md @@ -0,0 +1,213 @@ +--- +title: AppConnector auditor voor Partners +author: Eric Zwaal +date: 2025-01-21 +tags: Appconnector, inrichting, GetConnector +index: true +--- + +## Inleiding + +Sinds Profit 5 (najaar 2024) kennen we de AppConnector Auditor: een mooi hulpmiddel om snel inzicht te krijgen in een AppConnector. Voor jou als partner is het een hulpmiddel om te zien in hoeverre jouw integratie aan de best practices (en soms ook eisen) van AFAS voldoet. + +## Wat heb je nodig + +- AFAS Omgeving +- Een AppConnector die is ingericht zoals je dat ook bij een klant zou laten doen +- De juiste rechten: + - Autorisatie tool > Autorisatie > Algemeen > Beheer > App connector > Acties > AppConnector auditor + +## Gebruik van de auditor + +1. Ga in het menu naar `Algemeen > Beheer > App connector` +2. Open de eigenschappen van de AppConnector die je wilt analyseren +3. Klik naast het rijtje tabbladen aan de linkerkant op `Acties` +4. Klik op de actie `Auditor (voor partners)` +5. Na een paar seconden krijg je de melding "Audit-informatie is gekopieerd naar het klembord". +6. Open een markdown-editor, bijvoorbeeld [StackEdit](https://stackedit.io/) +7. Maak het linkerpaneel leeg en plak daarin de inhoud van het klembord (CTRL + V) +8. In het rechterpaneel zie je nu een verslag over de AppConnector + +## Uitleg van de analyse + +Wat je te zien krijgt in de Auditor is natuurlijk afhankelijk van de AppConnector. In dit onderdeel behandel ik welke meldingen je mogelijk te zien krijgt, en wat je daarmee kan doen. Doordat er vertaling wordt toegepast kan een tekst er bij jou net wat anders uitzien. Ook de volgorde kan afwijken. + +### Jouw gegevens + +Deze sectie toont een aantal gegevens die wij bij AFAS van jou hebben. + +- Naam: De naam van jouw bedrijf. Omdat hier ook de factuur naar verstuurd wordt, is het van belang dat dit jouw officiële bedrijfsnaam is. +- Abonnementsnummer: Het nummer van het abonnement bij AFAS waar jouw partner-licentie onder valt. Dit is ook het eerste deel van het IntegrationId dat je meestuurt. +- Verantwoordelijke: De persoon die bij jou verantwoordelijk is voor de koppeling. Hij/zij is ook eerste aanspreekpunt vanuit AFAS. +- Projectleider bij AFAS: Jouw aanspreekpunt bij AFAS voor wat betreft de koppeling. Dat zal meestal een SystemIntegrator zijn. +- Status PEN test: Als je de resultaten van een PEN test hebt laten zien, geven wij daar een score aan; die zie je hier. Een Groene score is 3 jaar geldig, een Oranje score is 15 maanden geldig en een Rode score is 6 maanden geldig. Dit is gerekend vanaf de datum die op het PEN-testrapport genoemd wordt. +- Einddatum geldigheid PEN test: Dit is de datum van de laatste PEN test, opgehoogd met de geldigheidsduur (zie punt hierboven). Na deze datum voldoe je formeel niet meer als partner en zal de opzegtermijn van AFAS (12 maanden) ingaan. Na afloop van de opzegtermijn heeft AFAS het recht om het partnercontract éénzijdig te beëindigen. + +### IntegrationId + +Deze sectie toont gegevens die gekoppeld zijn aan jouw IntegrationId. Als je meerdere koppelingen met AFAS vermarkt, heb je ook meerdere IntegrationId's en zal deze sectie meerdere keren getoond worden. + +- Projectcode: Voor elke integratie hebben we een project gemaakt. Als je partner bent geworden na maart 2023, bevat dit project ook jouw onboardingstaken. +- Omschrijving: Omschrijving van het project, maar ook van jouw plekje in de lijst met gecertificeerde koppelingen. +- Status van de certificering: Status +- Aantal openstaande projecttaken: Als er 12 maanden na de startdatum van de certificering nog taken openstaan, zal AFAS je benaderen voor een laatste gesprek. Lukt het niet om alle taken af te handelen, dan zal het partnercontract beëindigd worden. +- Artikelcode: Nummer van het artikel waarmee je zichtbaar bent op de partnersite. +- Introductie, Beschrijving, Website: de velden zoals je die hebt ingevuld via https://partner.afas.nl/mijn-paginas. +- Geblokkeerd: "Ja" als jouw koppeling niet getoond wordt. Als je niet weet waarom dat is, neem dan contact op met de SystemIntegrators. + +### Checklist voor jouw certificeringsproces + +Als alle punten een vinkje hebben dan is de certificering afgerond. Ben je van mening dat een vinkje onterecht uit staat? Neem dan contact op met jouw contactpersoon ("Projectleider") bij AFAS. + +- [ ] Je gegevens bij AFAS zijn compleet: Zie [hierboven](#jouw-gegevens) welke gegevens er nog missen. +- [ ] Je PENtest is geldig: Dit vinkje staat aan zolang jouw PENtest geldig is. Zie [hierboven](#jouw-gegevens). +- [ ] Je integratie wordt getoond op onze website: Controleer bij het onderdeel [IntegrationId](#integrationid) of Introductie, Beschrijving en Website zijn ingevuld. +- [ ] Je hebt alle projecttaken afgehandeld: Je hebt 12 maanden de tijd om alle projecttaken af te ronden. Zie ook [hierboven](#integrationid). + +### Checklist voor jouw integratie + +Deze sectie is wat minder zwart/wit. In de basis heb je een goede integratie als alle punten een vinkje hebben, maar dat is niet sluitend. Als er situaties zijn waarin een vinkje onterecht uitgevinkt staat, dan zul je dat moeten bespreken met jouw projectleider bij de SystemIntegrators. +Ook als alle punten een vinkje hebben, kan het zijn dat AFAS nog wil dat je aanpassingen doorvoert. + +### Checklist voor punten die je moet behandelen in je implementatiedocument + +Deze lijst hangt nauw samen met de [Checklist voor jouw integratie](#checklist-voor-jouw-integratie). Bij de beoordeling van jouw implementatiedocument zullen deze punten meegenomen worden. + +### App Connector + +In dit onderdeel zie je de naam van de App Connector, en worden meldingen getoond die betrekking hebben op de inrichting van de AppConnector zelf. Dit is vooral bedoeld voor de eindgebruiker. + + +### UpdateConnectoren + +Deze sectie geeft een lijst van UpdateConnectoren die aan te roepen zijn. + +### Overige Connectoren + +Deze sectie geeft een lijst van overige Connectoren die aan te roepen zijn. Denk daarbij aan connectoren om bijlagen op te halen. + +### GetConnectoren: Algemeen + +Dit is een belangrijke sectie. Eerst worden er meldingen gegeven die voor meerdere GetConnectoren gelden. Daarna worden de GetConnectoren stuk voor stuk getoond. + +#### Er worden onbekende velden gebruikt. + +Er is een GetConnector (of meerdere) waarin een veld gebruikt wordt dat niet in jouw omgeving beschikbaar is. Vaak is dat een vrij veld. Vraag je leverancier om welk veld het gaat; mogelijk is dat nodig om de integratie goed te laten functioneren. + +#### Er worden vrije velden gebruikt. + +Zorg ervoor dat je deze ook aanbiedt en dat je in het implementatiedocument hier aandacht aan besteedt. Vrije velden kun je vanuit jouw AFAS testomgeving exporteren en als downloadbaar bestand aanbieden, samen met de GetConnectoren. + +#### De volgende autorisaties worden toegepast. + +Veel GetConnectoren tonen alleen gegevens die door de eindgebruiker in de autorisatiefilters zijn toegestaan. Door in je implementatiedocument te vermelden welke filters van toepassing zijn op jouw integratie, kan de AFAS beheerder alles goed inrichten. + +#### EnSe en DvSn worden beide gebruikt. + +Kort gezegd: AFAS Profit kent 2 verschillende nummers die het dienstverband aanduiden. Als je die door elkaar heen gebruikt, heb je kans op lastig te traceren fouten. [Lees daarom dit artikel goed door](./howto-bi#medewerkers-en-dienstverband). Schroom niet om dit te overleggen tijdens een afspraak met een SystemIntegrator. + +#### Er worden Financiële mutaties opgehaald, maar **Gewijzigde boekingsdagen** wordt niet gebruikt. + +Haal je veel Financiële mutatie op? Gebruik dan ook de GetConnector `Gewijzigde boekingsdagen`. [Lees dit artikel goed door](https://help.afas.nl/help/NL/SE/App_Cnnct_View_Audit.htm#o79118). + +Mogelijk ben je ook geïnteresseerd in het ophalen van verwijderde mutaties. [Lees daarvoor dit artikel](https://help.afas.nl/help/NL/SE/App_Cnnct_Deleted_Data.htm#o124753). + +#### Er wordt Nacalculatie opgehaald, maar **Gewijzigde boekingsdagen nacalculatie** wordt niet gebruikt. + +Haal je veel nacalculatieregels op? Gebruik dan ook de GetConnector `Gewijzigde boekingsdagen nacalculatie`. [Lees dit artikel goed door](https://help.afas.nl/help/NL/SE/App_Cnnct_View_Audit.htm#o95619). + +Mogelijk ben je ook geïnteresseerd in het ophalen van verwijderde nacalculatie. [Lees daarvoor dit artikel](https://help.afas.nl/help/NL/SE/App_Cnnct_Deleted_Data.htm#o124754). + +#### Hieronder staan de autorisaties die van toepassing zijn en hoe de rechten in jouw omgeving zijn toegekend. + +Deze sectie geeft de AFAS beheerder inzicht in de inrichting van de autorisatie die effect heeft op jouw integratie. Elke klant zal dit anders hebben ingericht. + +### GetConnectoren: Meldingen per GetConnector + +#### Aantal velden, Optimale take + +Informatie over de GetConnector. De Optimale take is gebaseerd op best practices en berekend als 150.000 / \[Aantal velden\]. + +#### Dit is een meegeleverde Profit GetConnector. + +Maak altijd een eigen set GetConnectoren. +Het is verleidelijk om de standaard Profit-GetConnectoren te gebruiken, maar de nadelen wegen zwaarder: +- Er zitten velden in die je niet gebruikt +- Je kunt ze niet aanpassen, dus als je een veld mist moet je daar alsnog een eigen GetConnector voor maken +- Er kan geen filter worden toegepast. Jij kan nog een filter meegeven in de URL, maar de AFAS beheerder heeft niet de mogelijkheid om + +#### Ongeldige naam. Deze GetConnector heeft een naam die begint met "Profit_". + +Geef jouw GetConnectoren bij voorkeur een naam die begint met jouw bedrijfsnaam, of de naam van de app die je koppelt. Daarmee voorkom je dat er conflicten optreden als een klant meerdere integraties heeft. + +#### Deze GetConnector heeft 1 of meer onbekende velden. + +Zie [hierboven](#er-worden-onbekende-velden-gebruikt). + +#### Deze GetConnector heeft 1 of meer vrije velden. + +Zie [hierboven](#er-worden-vrije-velden-gebruikt). + +#### Deze GetConnector heeft 1 of meer velden met een punt in de naam. + +Dat kan een probleem geven als je in de URL op deze velden wilt filteren of sorteren. Pas de naam aan zodat er geen punt in voorkomt. + +#### Deze GetConnector heeft velden die zijn gemarkeerd als privacy-gevoelig. + +In Profit is een set met gegevens gekenmerkt als privacy-gevoelig. In deze sectie zie je welke van die velden gebruikt worden in de integratie. Kijk de lijst goed door; ga het gesprek aan met de leverancier als er velden tussen staan die de gekoppelde app niet noodzakelijkerwijs nodig heeft om goed te functioneren. + +#### Deze GetConnector gebruikt verdichting. Controleer of dat terecht is. + +Verdichting is een fantastich hulpmiddel om je minder gegevens op te halen, of om totalen te laten bepalen. + +#### Deze GetConnector heeft velden met een speciaal formaat. + +Je kan in een GetConnector een veld op een andere manier weergeven; bijvoorbeeld een datum/tijd als enkel datum of als een ander datumformaat. In veel gevallen wijzigt daardoor het veldtype. Dat is op zich geen probleem. Als je echter op dit gewijzigde veldtype gaat filteren of sorteren, maakt dat de GetConnector vele malen trager, vooral als er veel gegevens in de brontabel zitten. Dat kan oplopen tot meer dan een factor 100! + +#### De integratie gebruikt gegevens per dienstverband, maar deze GetConnector haalt velden uit Actuele gegevens per arbeidsverhouding. + +Actuele gegevens per arbeidsverhouding toont enkel gegevens uit het hoofddienstverband. Aangezien jouw integratie op andere plekken gegevens per dienstverband ophaalt, kan het zijn dat deze GetConnector de verkeerde gegevens toont. Dit kan lastig te traceren fouten veroorzaken. [Lees daarom dit artikel goed door](./howto-bi#medewerkers-en-dienstverband). Schroom niet om te overleggen met een SystemIntegrator. + +#### Deze GetConnector haalt velden uit een tabel met gegevens per dienstverband, maar nergens in de integratie wordt Dienstverbandnummer opgehaald. + +Als een medewerker meerdere dienstverbanden heeft, kan dit dubbele regels tot gevolg hebben. [Lees dit artikel goed door](./howto-bi.md#medewerkers-en-dienstverband) voor meer informatie over meerdere dienstverbanden. Plan ook gerust een overleg in met een SystemIntegrator. + +#### Veld **naam** of **omschrijving** wordt opgehaald uit een hoger niveau. + +Haal je veel gegevens op met deze GetConnector? Maak 'm dan zo clean mogelijk, met alleen velden uit de hoofdtabel. Redundante gegevens haal je met een aparte GetConnector op uit de betreffende tabel. Dat scheelt veel bandbreedte en ook uitvoeringstijd. + +#### Deze GetConnector heeft (mogelijk) een cyclische verwijzing. + +Het lijkt erop dat er velden worden opgehaald uit een tabel, meerdere verwijzingen diep, terwijl die tabel ook direct beschikbaar is. Controleer dat. + +#### Er worden verwijzingen gevolgd naar een tabel die ook als alias beschikbaar is. + +Een zogenaamde alias staat in het linkerpaneel, waarvandaan je velden kiest en in de gegevensverzameling toevoegt. Het is in de meeste gevallen best practice om velden zoveel mogelijk direct uit zo'n alias te halen, omdat er anders dubbele JOINs gelegd worden. + +#### Deze GetConnector is geautoriseerd. + +Hier zie je welke autorisatiefilters van toepassing zijn op deze specifieke GetConnector. Als een bepaalde autorisatie er niet bij staat, dan wordt die autorisatie niet toegepast op de GetConnector. Mocht je toch gegevens willen tegenhouden, maak dan gebruik van een filter in de GetConnector zelf. + +#### Indexen + +In deze sectie zie je alle indexen die op de hoofdtabel liggen. Als dat een tabel is met veel regels, zorg er dan voor dat je zoveel mogelijk gebruik maakt van deze indexen. Dat geldt voor filteren en voor sorteren. Als je dat niet doet, kan dat een dramatische impact op de performance van de GetConnector hebben. + +Gebruik bij voorkeur index 1; dat is de geclusterde, unieke primary key van de tabel. De velden die hier in staan, geven een unieke identificatie van elke regel. Een paar vuistregels: +- Geef altijd een sortering mee in de URL +- Sorteer op zoveel mogelijk velden van index 1, in de opgegeven volgorde van de velden. Dus als er een index ligt op Medewerker, Begindatum: sorteer dan in ek geval op die 2 velden. +- Sommige velden zijn helaas niet direct beschikbaar. Een Systemintegrator kan jouw GetConnector eventueel aanpassen en de verborgen velden toevoegen. +- Als je filtert in de GetConnector, doe dat dan ook zoveel mogelijk op indexvelden. +- Is index 1 niet beschikbaar of niet logisch voor jou? Gebruik dan één van de andere indexen. Let op, die zijn niet altijd uniek. + + +#### Filters + +Deze sectie toont de filters die in de GetConnector zijn opgeslagen. Controleer of ze voor alle klanten van toepassing zijn. Zo niet, geef dan een filter mee bij de aanroep in de URL. Of besteed er aandacht aan in je implementatiedocument. +Omdat niet alle GetConnectoren de filterautorisatie in de klantomgeving respecteren, is het vaak nodig dat de klant zelf ook aanpassingen moet doen in het filter. + +#### Langzaam filter + +Deze GetConnector heeft een filter dat slecht presteert. In een gecertificeerde koppeling is dat niet toegestaan; het is namelijk niet ondenkbaar dat door zo'n filter een GetConnector meer dan 100x zo langzaam wordt. + + + diff --git a/MarkdownPages/Profit/nl/app-connector-auditor.md b/MarkdownPages/Profit/nl/app-connector-auditor.md new file mode 100644 index 00000000..eb0e679e --- /dev/null +++ b/MarkdownPages/Profit/nl/app-connector-auditor.md @@ -0,0 +1,125 @@ +--- +title: AppConnector auditor +author: Eric Zwaal +date: 2025-01-21 +tags: Appconnector, inrichting, GetConnector +index: true +--- + +## Inleiding + +Sinds Profit 5 (najaar 2024) kennen we de AppConnector Auditor: een mooi hulpmiddel om snel inzicht te krijgen in een AppConnector. Dat is met name handig als je wilt weten wat een externe partij bij jou uitvraagt. + +## Wat heb je nodig + +- AFAS Omgeving +- Een AppConnector die is ingericht voor een koppeling met een externe partij +- De juiste rechten: + - Autorisatie tool > Autorisatie > Algemeen > Beheer > App connector > Acties > AppConnector auditor + +## Gebruik van de auditor + +1. Ga in het menu naar `Algemeen > Beheer > App connector` +2. Open de eigenschappen van de AppConnector die je wilt analyseren +3. Klik naast het rijtje tabbladen aan de linkerkant op `Acties` +4. Klik op de actie `Auditor` +5. Na een paar seconden krijg je de melding "Audit-informatie is gekopieerd naar het klembord". +6. Open een markdown-editor, bijvoorbeeld [StackEdit](https://stackedit.io/) +7. Maak het linkerpaneel leeg en plak daarin de inhoud van het klembord (CTRL + V) +8. In het rechterpaneel zie je nu een verslag over de AppConnector + +## Uitleg van de analyse + +Wat je te zien krijgt in de Auditor is natuurlijk afhankelijk van de AppConnector. In dit onderdeel behandel ik welke meldingen je mogelijk te zien krijgt, en wat je daarmee kan doen. Doordat er vertaling wordt toegepast kan een tekst er bij jou net wat anders uitzien. Ook de volgorde kan afwijken. + +### App Connector + +In dit onderdeel zie je de naam van de App Connector, en worden meldingen getoond die betrekking hebben op de inrichting van de AppConnector zelf + +#### Autorisatiegroep heeft meer dan 1 gebruiker. + +In de meeste gevallen maak je voor elke AppConnector een eigen Autorisatiegroep aan en een eigen systeemgebruiker. + +#### Er zijn geen tokens uitgedeeld. + +Zonder tokens kan een externe partij niet met je koppelen. Ga naar het tabblad "Gebruikerstokens", klik op `Nieuw` en maak een token. De omschrijving is puur informatief. Het token ziet er zo uit: `188537B2CBF2741E5B5A1620D15F963F93159C83CC55C4652B02D1D1ABA7A6D24`. Als de externe partij om het token vraagt, geef 'm dan altijd helemaal. + +> LET OP: Een token geeft toegang tot gegevens uit Profit en is daarom zeer waardevol. Zet 'm nooit zomaar in een onbeveiligde mail, en zorg ervoor dat alleen de externe partij 'm krijgt. Laat een token niet rondslingeren! + +#### Er is meer dan 1 token uitgedeeld. + +Voor de meeste koppelingen is er maar één token nodig. Verwijder tokens die niet gebruikt worden om misbruik te voorkomen. Ook als er meerdere tokens voor één gebruiker zijn, geven ze nog steeds toegang tot jouw gegevens in Profit. + +#### Er is een token uitgedeeld met een beperkte geldigheidsduur. + +Je hebt in de AppConnector op tabblad `Algemeen` een geldigheidsduur opgegeven en daarna een token gemaakt. Dat betekent dat het token op een gegeven moment niet meer geldig is. Zorg ervoor dat je vóór de vervaldatum een nieuw token hebt verstrekt. + +#### Er is een token uitgedeeld dat langer dan 3 maanden niet aangeroepen is. + +Een token die al langere tijd niet aangeroepen is, wordt waarschijnlijk niet meer gebruikt. Toch geeft het nog steeds toegang tot jouw Profit omgeving. Verwijder tokens die niet meer gebruikt worden om misbruik te voorkomen. + +#### Er is een token meer dan 12 maanden geleden uitgedeeld. + +Het is goed gebruik om tokens regelmatig te vervangen. Volg deze stappen: +1. Maak een nieuw token, voor dezelfde gebruiker +2. Stuur dit token op een veilige manier naar de derde partij die de koppeling verzorgt. Let op: Een token geeft toegang tot gegevens uit Profit en is daarom zeer waardevol. Zet 'm nooit zomaar in een onbeveiligde mail, en zorg ervoor dat alleen de externe partij 'm krijgt. Laat een token niet rondslingeren! +3. Als het nieuwe token in gebruik genomen is, kun je dat zien aan de "Datum laatst gebruikt" op het tabblad Gebruikerstokens. +4. Verwijder het oude token. + +#### Connectorgebruiker heeft toegang tot Profit Windows. + +Maak altijd voor elke koppeling een eigen AppConnector aan. +Maak voor elke AppConnector een eigen autorisatiegroep aan, waarop je de juiste rechten inricht. +Maak voor elke AppConnector één systeemgebruiker aan. Deze heeft géén toegang nodig tot Profit Windows. +Gebruik voor een AppConnector geen medewerker! Het maakt het moeilijk om de autorisatie goed in te richten. Bovendien vervalt alle autorisatie zodra de medewerker uit dienst gaat. De GetConnectoren geven dan mogelijk geen data meer. + +#### Er zijn geen IP-adres restricties ingericht. + +Voor extra beveiliging richt je IP-restricties in. Vraag de leverancier vanuit welk IP-adres de Connectoren worden aangeroepen. Op het tabblad "IP-restricties" maak je een nieuwe regel aan voor dat IP-adres met `Toegang` = "Toestaan". Vanaf nu zijn alle andere IP-adressen geblokkeerd. +Tijdens de testfase van een integratie kan het nodig zijn om ook de IP-adressen van AFAS Connect toe te staan. + +#### Aanroepen vanuit de IP-adressen van AFAS Connect zijn toegestaan. + +Zodra de testfase van een integratie voorbij is, is het niet meer nodig om vanuit AFAS Connect jouw omgeving te benaderen. Verwijder daarom op het tabblad "IP-restricties" de regel(s) die toegang toestaan vanuit AFAS Connect. +Dat zijn de IP-adressen `52.174.142.76` en `52.174.142.140`. + +### UpdateConnectoren + +Deze sectie geeft een lijst van UpdateConnectoren die aan te roepen zijn. + +### Overige Connectoren + +Deze sectie geeft een lijst van overige Connectoren die aan te roepen zijn. Denk daarbij aan connectoren om bijlagen op te halen. + +### GetConnectoren: Algemeen + +Dit is een belangrijke sectie. Eerst worden er meldingen gegeven die voor meerdere GetConnectoren gelden. Daarna worden de GetConnectoren stuk voor stuk getoond. + +#### Er worden onbekende velden gebruikt. + +Er is een GetConnector (of meerdere) waarin een veld gebruikt wordt dat niet in jouw omgeving beschikbaar is. Vaak is dat een vrij veld. Vraag je leverancier om welk veld het gaat; mogelijk is dat nodig om de integratie goed te laten functioneren. + +#### Hieronder staan de autorisaties die van toepassing zijn en hoe de rechten in jouw omgeving zijn toegekend. + +Veel GetConnectoren respecteren de filterautorisatie die je in Profit hebt ingericht. Deze sectie geeft jou inzicht in welke autorisatiefilters er gebruikt worden door de Token-gebruikers, en welke rechten er zijn toegekend. Als een Token-gebruiker teveel rechten heeft, kan er sprake zijn van een datalek. Een leverancier van VoIP-diensten hoeft bijvoorbeeld vaak niets te weten over de buitendienstmedewerkers, terwijl een planningsapplicatie juist geen rechten hoeft te hebben op de medewerkers op kantoor. + +### Meldingen per GetConnector + +#### Deze GetConnector heeft velden die zijn gemarkeerd als privacy-gevoelig. + +In Profit is een set met gegevens gekenmerkt als privacy-gevoelig. In deze sectie zie je welke van die velden gebruikt worden in de integratie. Kijk de lijst goed door; ga het gesprek aan met de leverancier als er velden tussen staan die de gekoppelde app niet noodzakelijkerwijs nodig heeft om goed te functioneren. + +#### Deze GetConnector is geautoriseerd. + +Hier zie je welke autorisatiefilters van toepassing zijn op deze specifieke GetConnector. Als een bepaalde autorisatie er niet bij staat, dan wordt die autorisatie niet toegepast op de GetConnector. Mocht je toch gegevens willen tegenhouden, maak dan gebruik van een filter in de GetConnector zelf. + +#### Filters + +Deze sectie toont de filters die in de GetConnector zijn opgeslagen. Dat wordt vaak al door de leverancier gedaan. Controleer of de filters logisch zijn. +Omdat niet alle GetConnectoren de filterautorisatie in de klantomgeving respecteren, is het vaak nodig dat je zelf ook aanpassingen moet doen in het filter. + +#### Langzaam filter + +Deze GetConnector heeft een filter dat slecht presteert. Pas dat aan indien mogelijk, eventueel in overleg met je leverancier. + + diff --git a/MarkdownPages/sb/en/Change tracking.md b/MarkdownPages/sb/en/change-tracking.md similarity index 100% rename from MarkdownPages/sb/en/Change tracking.md rename to MarkdownPages/sb/en/change-tracking.md diff --git a/MarkdownPages/sb/en/Howto payroll.md b/MarkdownPages/sb/en/howto-payroll.md similarity index 100% rename from MarkdownPages/sb/en/Howto payroll.md rename to MarkdownPages/sb/en/howto-payroll.md diff --git a/MarkdownPages/sb/en/Howto pos.md b/MarkdownPages/sb/en/howto-pos.md similarity index 100% rename from MarkdownPages/sb/en/Howto pos.md rename to MarkdownPages/sb/en/howto-pos.md diff --git a/MarkdownPages/sb/en/Howto purchasejournal.md b/MarkdownPages/sb/en/howto-purchasejournal.md similarity index 100% rename from MarkdownPages/sb/en/Howto purchasejournal.md rename to MarkdownPages/sb/en/howto-purchasejournal.md diff --git a/MarkdownPages/sb/en/Howto relations.md b/MarkdownPages/sb/en/howto-relations.md similarity index 100% rename from MarkdownPages/sb/en/Howto relations.md rename to MarkdownPages/sb/en/howto-relations.md diff --git a/MarkdownPages/sb/en/Howto salesinvoice.md b/MarkdownPages/sb/en/howto-salesinvoice.md similarity index 100% rename from MarkdownPages/sb/en/Howto salesinvoice.md rename to MarkdownPages/sb/en/howto-salesinvoice.md diff --git a/MarkdownPages/sb/en/Howto salesjournal.md b/MarkdownPages/sb/en/howto-salesjournal.md similarity index 100% rename from MarkdownPages/sb/en/Howto salesjournal.md rename to MarkdownPages/sb/en/howto-salesjournal.md diff --git a/MarkdownPages/sb/en/News howtos.md b/MarkdownPages/sb/en/news-howtos.md similarity index 100% rename from MarkdownPages/sb/en/News howtos.md rename to MarkdownPages/sb/en/news-howtos.md diff --git a/MarkdownPages/sb/en/News sb2.md b/MarkdownPages/sb/en/news-sb2.md similarity index 100% rename from MarkdownPages/sb/en/News sb2.md rename to MarkdownPages/sb/en/news-sb2.md diff --git a/MarkdownPages/sb/nl/Change tracking.md b/MarkdownPages/sb/nl/change-tracking.md similarity index 100% rename from MarkdownPages/sb/nl/Change tracking.md rename to MarkdownPages/sb/nl/change-tracking.md diff --git a/MarkdownPages/sb/nl/Howto payroll.md b/MarkdownPages/sb/nl/howto-payroll.md similarity index 100% rename from MarkdownPages/sb/nl/Howto payroll.md rename to MarkdownPages/sb/nl/howto-payroll.md diff --git a/MarkdownPages/sb/nl/Howto pos.md b/MarkdownPages/sb/nl/howto-pos.md similarity index 100% rename from MarkdownPages/sb/nl/Howto pos.md rename to MarkdownPages/sb/nl/howto-pos.md diff --git a/MarkdownPages/sb/nl/Howto purchasejournal.md b/MarkdownPages/sb/nl/howto-purchasejournal.md similarity index 100% rename from MarkdownPages/sb/nl/Howto purchasejournal.md rename to MarkdownPages/sb/nl/howto-purchasejournal.md diff --git a/MarkdownPages/sb/nl/Howto relations.md b/MarkdownPages/sb/nl/howto-relations.md similarity index 100% rename from MarkdownPages/sb/nl/Howto relations.md rename to MarkdownPages/sb/nl/howto-relations.md diff --git a/MarkdownPages/sb/nl/Howto salesinvoice.md b/MarkdownPages/sb/nl/howto-salesinvoice.md similarity index 100% rename from MarkdownPages/sb/nl/Howto salesinvoice.md rename to MarkdownPages/sb/nl/howto-salesinvoice.md diff --git a/MarkdownPages/sb/nl/Howto salesjournal.md b/MarkdownPages/sb/nl/howto-salesjournal.md similarity index 100% rename from MarkdownPages/sb/nl/Howto salesjournal.md rename to MarkdownPages/sb/nl/howto-salesjournal.md diff --git a/MarkdownPages/sb/nl/News howtos.md b/MarkdownPages/sb/nl/news-howtos.md similarity index 100% rename from MarkdownPages/sb/nl/News howtos.md rename to MarkdownPages/sb/nl/news-howtos.md diff --git a/MarkdownPages/sb/nl/News sb2.md b/MarkdownPages/sb/nl/news-sb2.md similarity index 100% rename from MarkdownPages/sb/nl/News sb2.md rename to MarkdownPages/sb/nl/news-sb2.md diff --git a/menustructures/multilanguage_menu.json b/menustructures/multilanguage_menu.json index 187038e2..6d2b50e7 100644 --- a/menustructures/multilanguage_menu.json +++ b/menustructures/multilanguage_menu.json @@ -72,7 +72,7 @@ "en": [ { "name": "Quick start", - "path": "en/Howto-quickstart.md", + "path": "en/howto-quickstart.md", "subtitle": "", "tags": ["quickstart", "basics"], "featured": true, @@ -81,7 +81,7 @@ }, { "name": "Get dossier and attachment", - "path": "en/Howto-bijlage-dossier.md", + "path": "en/howto-bijlage-dossier.md", "subtitle": "Retrieve documents and attachments from the system", "tags": ["documents", "attachments", "retrieval"], "featured": false, @@ -90,7 +90,7 @@ }, { "name": "Journal entry sales", - "path": "en/Howto-finance-mutation.md", + "path": "en/howto-finance-mutation.md", "subtitle": "Create financial mutations for sales transactions", "tags": ["finance", "sales", "journal"], "featured": false, @@ -99,7 +99,7 @@ }, { "name": "Journal entry purchase", - "path": "en/Howto-finance-mutation-purch.md", + "path": "en/howto-finance-mutation-purch.md", "subtitle": "Create financial mutations for purchase transactions", "tags": ["finance", "purchase", "journal"], "featured": false, @@ -108,7 +108,7 @@ }, { "name": "HRM Employee AD", - "path": "en/Howto-medewerker-ad.md", + "path": "en/howto-medewerker-ad.md", "subtitle": "Integrate employee data with Active Directory", "tags": ["hrm", "employee", "active-directory"], "featured": false, @@ -117,7 +117,7 @@ }, { "name": "Flex Customer agreement", - "path": "en/Howto-flex.md", + "path": "en/howto-flex.md", "subtitle": "Set up flexible customer agreements", "tags": ["flex", "customer", "agreement"], "featured": false, @@ -126,7 +126,7 @@ }, { "name": "Mobility", - "path": "en/Howto-mobility.md", + "path": "en/howto-mobility.md", "subtitle": "Configure mobility solutions and integrations", "tags": ["mobility", "integration"], "featured": false, @@ -135,7 +135,7 @@ }, { "name": "Connecting payroll to salary admin.", - "path": "en/Howto-la-sa.md", + "path": "en/howto-la-sa.md", "subtitle": "Link payroll administration with salary administration", "tags": ["payroll", "salary", "administration"], "featured": false, @@ -146,7 +146,7 @@ "nl": [ { "name": "Quick start", - "path": "nl/Howto-quickstart.md", + "path": "nl/howto-quickstart.md", "subtitle": "Snel aan de slag met de API", "tags": ["quickstart", "basics"], "featured": true, @@ -155,7 +155,7 @@ }, { "name": "Dossier en bijlage ophalen", - "path": "nl/Howto-bijlage-dossier.md", + "path": "nl/howto-bijlage-dossier.md", "subtitle": "Documenten en bijlagen uit Profit ophalen", "tags": ["documenten", "bijlagen", "ophalen"], "featured": false, @@ -164,7 +164,7 @@ }, { "name": "HRM Medewerker AD", - "path": "nl/Howto-medewerker-ad.md", + "path": "nl/howto-medewerker-ad.md", "subtitle": "Medewerkergegevens integreren met Active Directory", "tags": ["hrm", "medewerker", "active-directory"], "featured": false, @@ -173,7 +173,7 @@ }, { "name": "ATS integratie", - "path": "nl/Howto-ats.md", + "path": "nl/howto-ats.md", "subtitle": "Applicant Tracking System integreren", "tags": ["ats", "recruitment", "integratie"], "featured": false, @@ -182,7 +182,7 @@ }, { "name": "Plaatsing", - "path": "nl/Howto-plaatsing.md", + "path": "nl/howto-plaatsing.md", "subtitle": "Plaatsingen en uitzendingen beheren", "tags": ["plaatsing", "uitzending", "hrm"], "featured": false, @@ -191,7 +191,7 @@ }, { "name": "Workflow acties", - "path": "nl/Howto-workflow-acties.md", + "path": "nl/howto-workflow-acties.md", "subtitle": "Workflow acties configureren en uitvoeren", "tags": ["workflow", "acties", "automatisering"], "featured": false, @@ -200,7 +200,7 @@ }, { "name": "Mobiliteit", - "path": "nl/Howto-mobility.md", + "path": "nl/howto-mobility.md", "subtitle": "Mobiliteitsoplossingen en integraties configureren", "tags": ["mobiliteit", "integratie"], "featured": false, @@ -209,7 +209,7 @@ }, { "name": "Integreren met BI", - "path": "nl/Howto-bi.md", + "path": "nl/howto-bi.md", "subtitle": "Business Intelligence integratie opzetten", "tags": ["bi", "business-intelligence", "integratie"], "featured": false, @@ -218,7 +218,7 @@ }, { "name": "Financiële mutatie verkoop", - "path": "nl/Howto-finance-mutation.md", + "path": "nl/howto-finance-mutation.md", "subtitle": "Financiële mutaties voor verkooptransacties aanmaken", "tags": ["financien", "verkoop", "journaal"], "featured": false, @@ -227,7 +227,7 @@ }, { "name": "Financiële mutatie inkoop", - "path": "nl/Howto-finance-mutation-purch.md", + "path": "nl/howto-finance-mutation-purch.md", "subtitle": "Financiële mutaties voor inkooptransacties aanmaken", "tags": ["financien", "inkoop", "journaal"], "featured": false, @@ -236,7 +236,7 @@ }, { "name": "Flex Klantovereenkomst", - "path": "nl/Howto-flex.md", + "path": "nl/howto-flex.md", "subtitle": "Flexibele klantovereenkomsten opzetten", "tags": ["flex", "klant", "overeenkomst"], "featured": false, @@ -245,7 +245,7 @@ }, { "name": "Loonadmin. aansluiten op salarisadmin.", - "path": "nl/Howto-la-sa.md", + "path": "nl/howto-la-sa.md", "subtitle": "Loonadministratie koppelen aan salarisadministratie", "tags": ["loon", "salaris", "administratie"], "featured": false, @@ -254,7 +254,7 @@ }, { "name": "Btw-terugvordering via de API", - "path": "nl/Howto-vat-reclaim.md", + "path": "nl/howto-vat-reclaim.md", "subtitle": "BTW terugvordering via API afhandelen", "tags": ["btw", "terugvordering", "api"], "featured": false, @@ -267,23 +267,23 @@ "en": [ { "name": "Profit 7 Releasenotes", - "path": "en/News-profit7.md" + "path": "en/news-profit7.md" }, { "name": "Profit 6 Releasenotes", - "path": "en/News-profit6.md" + "path": "en/news-profit6.md" }, { "name": "Profit 5 Releasenotes", - "path": "en/News-profit5.md" + "path": "en/news-profit5.md" }, { "name": "Profit 4 Releasenotes", - "path": "en/News-profit4.md" + "path": "en/news-profit4.md" }, { "name": "Profit 3 Releasenotes", - "path": "en/News-profit3.md" + "path": "en/news-profit3.md" }, { "name": "API Documentation News", @@ -294,23 +294,23 @@ "nl": [ { "name": "Profit 7 Releasenotes", - "path": "nl/News-profit7.md" + "path": "nl/news-profit7.md" }, { "name": "Profit 6 Releasenotes", - "path": "nl/News-profit6.md" + "path": "nl/news-profit6.md" }, { "name": "Profit 5 Releasenotes", - "path": "nl/News-profit5.md" + "path": "nl/news-profit5.md" }, { "name": "Profit 4 Releasenotes", - "path": "nl/News-profit4.md" + "path": "nl/news-profit4.md" }, { "name": "Profit 3 Releasenotes", - "path": "nl/News-profit3.md" + "path": "nl/news-profit3.md" }, { "name": "API Documentatie Nieuws", From 1aebec298ab360feb5a77ecda8ec8fa404e48e0b Mon Sep 17 00:00:00 2001 From: Eric Zwaal Date: Tue, 29 Jul 2025 17:13:24 +0200 Subject: [PATCH 2/2] Workflow aanpassen --- scripts/IndexTools/ImportMarkdownData.py | 4 +- scripts/markdown-naming-check.py | 66 +++++++++++++++++++----- 2 files changed, 54 insertions(+), 16 deletions(-) diff --git a/scripts/IndexTools/ImportMarkdownData.py b/scripts/IndexTools/ImportMarkdownData.py index 3b721cee..3eb874d4 100644 --- a/scripts/IndexTools/ImportMarkdownData.py +++ b/scripts/IndexTools/ImportMarkdownData.py @@ -28,7 +28,7 @@ 'connection_timeout_seconds': 300 # Increase the timeout for imports }) -directory_path = Path(__file__).resolve().parents[2] / 'MarkdownPages' +directory_path = Path(__file__).resolve().parents[1] / 'markdownpages' def date_converter(o): if isinstance(o, date): @@ -85,7 +85,7 @@ def read_markdown_files(directory): print(f" Product: {product}, Language: {language}, Parts: {parts}") # Updated product filtering to include all valid products - valid_products = ['Profit', 'sb', 'Endpoint', 'Home', 'Main', 'Spec'] + valid_products = ['profit', 'sb', 'endpoint', 'home', 'main', 'spec'] if product not in valid_products: print(f" Skipping file - product '{product}' not in allowed list: {valid_products}") skipped_files += 1 diff --git a/scripts/markdown-naming-check.py b/scripts/markdown-naming-check.py index 1d45b9de..f9927590 100644 --- a/scripts/markdown-naming-check.py +++ b/scripts/markdown-naming-check.py @@ -2,11 +2,12 @@ """ Markdown File Naming Validator -This script validates that all markdown files in the repository start with a capital letter. +This script validates that all markdown files in the repository follow kebab-case naming convention, +except for AppConnectorAuditor* files which are allowed to be named differently. It recursively scans for *.md files and reports any violations. Author: GitHub Copilot -Date: 2025-07-14 +Date: 2025-07-29 """ import os @@ -61,7 +62,8 @@ def is_excluded(self, file_path: Path) -> bool: def validate_filename(self, file_path: Path) -> Tuple[bool, str]: """ - Validate that a markdown filename starts with a capital letter. + Validate that a markdown filename follows kebab-case convention. + Exception: AppConnectorAuditor* files are allowed to be named differently. Args: file_path: Path to the markdown file @@ -70,17 +72,50 @@ def validate_filename(self, file_path: Path) -> Tuple[bool, str]: Tuple of (is_valid, suggested_name) """ filename = file_path.name + basename = file_path.stem # filename without .md extension - # Check if filename starts with a capital letter (A-Z) - if filename and filename[0].isupper() and filename[0].isalpha(): + # Check if filename follows kebab-case convention: + # - All lowercase letters, numbers, hyphens, underscores, and dots + # - No spaces + # - No consecutive hyphens + # - Doesn't start or end with hyphen + kebab_pattern = r'^[a-z0-9]+([a-z0-9._-]*[a-z0-9])?$' + + if re.match(kebab_pattern, basename) and '--' not in basename and not basename.startswith('-') and not basename.endswith('-'): return True, filename - # Generate suggested correction - if filename: - suggested = filename[0].upper() + filename[1:] if filename else filename - return False, suggested + # Generate suggested correction (convert to kebab-case) + suggested_basename = self.to_kebab_case(basename) + suggested_filename = suggested_basename + '.md' + + return False, suggested_filename + + def to_kebab_case(self, text: str) -> str: + """ + Convert text to kebab-case. + + Args: + text: Input text to convert + + Returns: + kebab-case version of the text + """ + # Replace spaces with hyphens + text = re.sub(r'\s+', '-', text) + + # Insert hyphens before capital letters (for PascalCase/camelCase) + text = re.sub(r'([a-z])([A-Z])', r'\1-\2', text) + + # Convert to lowercase + text = text.lower() - return False, filename + # Clean up multiple hyphens + text = re.sub(r'-+', '-', text) + + # Remove leading/trailing hyphens + text = text.strip('-') + + return text def scan_directory(self) -> None: """Recursively scan directory for markdown files and validate naming.""" @@ -148,9 +183,9 @@ def print_report(self) -> None: print() print("SUMMARY:") - print("❌ Validation FAILED - Please rename the files above to start with a capital letter.") + print("❌ Validation FAILED - Please rename the files above to follow kebab-case convention.") else: - print("✅ All markdown files follow the naming convention!") + print("✅ All markdown files follow the kebab-case naming convention!") print("✅ Validation PASSED") def validate(self) -> bool: @@ -183,9 +218,12 @@ def main(): """Main entry point for the script.""" parser = argparse.ArgumentParser( - description="Validate markdown file naming conventions", + description="Validate markdown file naming conventions (kebab-case)", formatter_class=argparse.RawDescriptionHelpFormatter, epilog=""" +This script validates that markdown files follow kebab-case naming convention. +Exception: AppConnectorAuditor* files are allowed to be named differently. + Examples: python markdown-naming-check.py python markdown-naming-check.py --root-path ./docs @@ -203,7 +241,7 @@ def main(): parser.add_argument( "--exclude", nargs="*", - default=[], + default=["AppConnectorAuditor*.md"], help="Patterns to exclude from validation (glob-style)" )