Overview

AFAS Profit offers connectors to seamlessly integrate your Profit environment with external applications. This AFAS Profit connector provides microflows to easily connect your Mendix app with your AFAS Profit environment.

Use this module to set up your authentication with one or multiple environments. Then use the standard microflows to integrate the connectors with your own ideas.

For any questions or feedback feel free to contact the developer of this module.

Documentation

Description

AFAS Profit offers connectors to seamlessly integrate your Profit environment with external applications. The AFAS Profit connector enables you to easily connect your Mendix app to your AFAS Profit environment.

Use this module to set up your authentication with one or multiple environments. Then use the standard microflows to integrate the connectors with your own ideas.

Typical usage scenario

• Retrieve data from the AFAS database through its web services
• Update data in the AFAS database through its web services
• View failed integrations and troubleshoot these.
• Change failed integration messages and retry.
• Connect with multiple AFAS environments

Features and limitations

Features

• GetConnector: Retrieve data from AFAS
• UpdateConnector: Insert, update or delete data in AFAS
• ReportConnector: Retrieve PDF report from AFAS
• FileConnector: Retrieve files from storage in AFAS
• SubjectConnector: Retrieve files from subject items in AFAS
• ImageConnector: Retrieve images from storage in AFAS
• VersionConnector: Retrieve current AFAS Profit version
• MetaInfoConnector: Retrieve information about AppConnector and authorization in AFAS
• Logging of all AFAS integration activities
• Retry failed integrations.

Dependencies

• CommunityCommons
• Encryption module

Installation

This module is dependent on Community commons and Encryption. Make sure to download these modules before following the installation guide.

•  Install the CommunityCommons module from the marketplace to your application
•  Install the Encryption module from the marketplace to your application
•  Install this module into your Mendix application (9.6.11 and up) 

Do not modify this module, instead:

1. Add the security role AfasConnector.Administrator to an existing administrator role.
2. Add the security role AfasConnector.User to an existing user role.
3. Add the SNIP_AfasConnector snippet to a page accessible to administrators. Make sure this page is within one of your own modules. Optionally you can directly use the AfasConnector_Overview page.
4. Create a new module, e.g. 'AFAS_Interface'.
5. Add new pages, copy or reuse snippets and microflows from the _Use_Me folder in this module into the 'AFAS_Interface' module. For example, you can use the microflows within the _Use_me folder directly within your microflows.
6. Make sure the default constant 'IntegrationEnabled' is set to true, else the integration won't work.
7. In order to secure your AFAS token, it is required to enter an encryption key in the constant 'Encryption.EncryptionKey'.

Configuration

To set up the AFAS Profit connector, you'll need to have access to a token of an authenticated user.

1. Create an AppConnector in AFAS and generate an access token for this specific user.
2. Open the AFAS Profit connector page in the Mendix runtime that has the 'SNIP_AfasConnector'  snippet.
3. Click “Create new environment” or edit one of the three default environments
4. Give the environment a friendly name in the “Name” field
5. Select the type of AFAS environment (production, accept, test)
6. Enter the AFAS Online member number, consisting of five digits
7. Enter the authorization token in XML format
8. Activate the environment using the active or save button.
9. If everything was done correctly the environment will be active. The environment will automatically be tested and validated, after which the available GetConnectors and UpdateConnectors will be retrieved and shown as well. You can now use the standard microflows to create the integrations you desire!

In case you want to use multiple environments you can create a new environment with a different name. The module currently validates that only 1 environment with a specific name can be active. 

For using OTP you have to take the following steps:

1. Set the AFAS Token and Environment key in the Environment object using the SNIP_AfasConnector.
2. Once set-up you can use the one time password microflows in the OTP folder. This has several microflows and a page for the OTP set-up. In general it works like this:
3. When a user wants to do a call to AFAS the application should check of a OneTimeToken object existst for that user. If it does use that object for the Post or Put microflows.
4. When there is no object, use ACT_OneTimePassword_CreateNew microflow to start the process of creating a new request. This will trigger an email to the user (If set-up properly in the AFAS environment)
5. The user will see a pop-up in Mendix and should put the code that they received in their email in the field OTP code. After this they can validate it throught clicking on the button on the pop-up page.
6. This will then trigger a validation flow using ACT_OneTimePassword_ValidateAndSave which will store the token encrypted on the OneTimePassword object.
7. This object can now be used by your own microflows to trigger the Post or Put microflows for the One Time Password variants.

Using the module

You can use the microflows explained below inside your own microflows. These microflows will return an HttpResponse. You can use the Rule in the _Use_Me folder to check if the update was successful to improve your error handling.

• GetConnector (PRS_Standard_Get)
• 
  
• returns System.HttpResponse
• Connectorid – The name or id of the GetConnector
• QueryString – A string containing all the filters and sorting queries that you desire
• Skip – The number of records to skip for this retrieve
• Take – The number of records to take for this retrieve
• 
  
• UpdateConnector POST (PRS_Standard_Post)
• 
  
• returns System.HttpResponse
• Connectorid – The name or id of the UpdateConnector
• Request – The JSON input that the connector should use for the request body
• 
  
• UpdateConnector PUT (PRS_Standard_Put)
• 
  
• returns System.HttpResponse
• Connectorid – The name or id of the UpdateConnector
• Request – The JSON input that the connector should use for the request body
• 
  
• UpdateConnector DELETE (PRS_Standard_Delete)
• 
  
• returns System.HttpResponse
• Connectorid – The name or id of the UpdateConnector
• QueryString – A string value that the Connector will use as the query
• 
  
• MetaInfo connector (PRS_MetaInfo_Get)
• 
  
• returns System.HttpResponse
• Environment – An object of type AfasConnector.Environment to get MetaInfo from
• 
  
• ReportConnector (PRS_Standard_Report)
• 
  
• returns AfasConnector.CustomConnectorFile
• ReportId – The id of the report (refer to AFAS Help to determine the id)
• QueryString – A string value that the Connector will use as the query
• 
  
• ImageConnector (PRS_Standard_Image)
• 
  
• returns AfasConnector.CustomConnectorFile
• ImageId – The id of the image (refer to AFAS Help to determine the id)
• ImageFormat – Enumeration of the image size (original, thumbnail, medium)
• 
  
• FileConnector (PRS_Standard_File)
• 
  
• returns AfasConnector.CustomConnectorFile
• FileId – The id of the file to retrieve (refer to AFAS Help to determine the id)
• FileName – The original file name
• 
  
• SubjectConnector (PRS_Standard_Subject)
• 
  
• returns AfasConnector.CustomConnectorFile
• SubjectId – The subject id of the file to retrieve (refer to AFAS Help to determine the id)
• FileId – The id of the file to retrieve
• 
  
• VersionConnector – (PRS_Standard_Version)
• 
  
• returns String

Additional information

• The Constant 'IntegrationEnabled' is set to false by default. This will ensure that when restoring a database to a local or accept environment the runtime tokens will not immediately activate. With this you can set up your new environment first and when ready enable this constant.
• The constant IntegrationId is required for all certified AFAS partners to identify your connection at the AFAS platform. You can set it once in the runtime configuration for your entire Mendix application.
• This module can be used for multiple AFAS environments, you can use the multiple environment microflows instead of the standard ones. Here you have to enhance your microflows by retrieving the right environment using the name of the environment as input. This is the name you entered yourself on the configuration page.
• Inside the logging folder within Private there is a JSON and import mapping for the content of the AFAS HttpResponse. You can use this to show more user-friendly messages in the case of errors.
• There is no clear best practice in setting up your integrations. Each application will ask for its own specific design in behavior and handling of objects. This integration connector serves to call integrations with AFAS in a standardized way including logging. This should speed up the development process, enable better debugging and allow for general updates of the integration module when AFAS releases new patches. We plan to add our own best practices to this module. In case you have any questions or are looking for advice regarding your AFAS integrations. Feel free to contact the developer of this module.

Known issues

• None at the moment