NVXWUL Web Utility Library

Library App for Web Authorization and Messages.

Current Version: 2.0.21.0 as of Business Central 22.

Manual

Creation date: 2024/11/22
The current version of this manual can be found at:

https://www.navax.app/help.php?AppID=NVXWUL&L=en

☰ Contents

General

App Web Utility Library
This App provides Functions to send Requests to REST Webservices and logs outgoing REST Requests...

Tasks

Working with the App
MultiPart/Form-Data Helper
For the complex content-type MultiPart/Form-Data there is a helper codeunit for the createn of such contents added...
Create Test Webrequest
With this page you can test requests outgoing from business central...
Retention Policy
A separate retention policy has been provided for the web messages...

Appendix

Release Notes

Docs / NVXWUL Web Utility Library / General
General

This App provides Functions to send Requests to REST Webservices and logs outgoing REST Requests. The Authentifaction types OAuth2, Basic and Bearer Token are supported.

Docs / NVXWUL Web Utility Library / Tasks
Arbeiten mit der App

Web Authentifizierung

Within this Record endpoints and their Authentication Types and Authentication values are stored.

Authentifizierung Fields
Endpoint URL	Specifies the endpoint URL.
Type	Specifies the authorization type.

OAuth, Fields
This authentication type can be used to retrieve tokens from Microsoft Identy Platform authorisation servers. The option "Client Credentials" is supported as an OAuth2 flow.
OAuth URL	Specifies the OAuth token endpoint.
Client ID	Specifies the client id.
Client Secret	Specifies the client secret.

Basic, Fields
Username	Specifies the username.
Password	Specifies the password.

Bearer Token, Fields
Bearer Token Login Url	Specifies the Bearer Token Login Url.
Requires Encryption	Specifies if the Login Url requires the credentials to be passed encrypted.
Bearer Token Json Key	Specifies the Key of the Json Value in the Http Response from the Bearer Token Login, which contains the Bearer Token.
Username	Specifies the username.
Password	Specifies the password.

Encryption, Fields
Encryption Algorithm	Specifies the encryption algorithm to be used.
Encryption Key Secret	Specifies the key for a keyed cryptographic function.

API Key, Fields
API Key Header Name	Specifies the name of the request header to be used for the api key.
API Key	Specifies the api key.

OAuth-external, Fields
This authentication type can be used to retrieve tokens from authorisation servers outside the Microsoft Identy Platform. The option "Client Credentials" is supported as an OAuth2 flow.
OAuth2 Flow	Specifies which OAuth 2.0 flow you want to use.
OAuth URL	Specifies the OAuth token endpoint.
Client ID	Specifies the client id.
Client Secret	Specifies the client secret.
Scope	Specifies the scope of the token. If empty then * will be used.

Actions

Test Credentials and Connection
Sends a HTTP GET request with the provided credentials to the endpoint, to check if the endpoint can be reached and to check if the credentials are correct. If Bearer Token or OAuth2 authentication is being used, an additional request will be made to check if the provided credentials result in a valid token. The response of the tested webservice is being displayed as a message.
Create Test Webrequest
Creates a test webrequest with this authentification.

Web Messages

With this Record HTTP Requests can be created and sent to the Endpoints, from the WebAuthentication Record. The sent Requests are being retent for one month.

Fields
Entry No.	Specifies the number of the record.
Date and Time	Specifies the date and time when the record was created.
Method	Specifies the web request method.
Target URL	Specifies the targeted url.
Payload	Specifies the sent payload of the request.
Response	Specifies the payload of the received response.
Response Reason Phrase	Specifies the http reason phrase of the received response.
Response Is Success Status	Specifies if the http request was accepted or denied.
Response Status Code	Specifies the http reason status code.

Procedures

CreateMessage

Parameters

RequestType Enum "Http Request Type" -> the HTTP Method of the Request to be sent
TargetURL Text[250] -> the URL of the Endpoint
RequestContent Text -> the Request Body

AddWebMessageHeader

Parameter

HeaderType Enum "WULWebMessageHeaderTypeNVX" -> Type of the HTTP Header (Request or Content Header)
Name Text -> Name of the Header
Value Text -> Value of the Header

AddWebMessageAuthorization

Parameter

HeaderType Enum "WULWebMessageHeaderTypeNVX" -> Type of the HTTP Header (Request or Content Header)
WebAuthorization Record "WULWebAuthorizationNVX" -> the configured authorization

SendMessage

Parameter

var ResponseMessage: HttpResponseMessage -> the Response of the Receiver

procedure ExecuteWebService(Payload: Text; WebAuthorization: Record WULWebAuthorizationNVX; EndpointURL: Text)
var
    WebMessage: Record WULWebMessageNVX;
    ResponseMessage: HttpResponseMessage;
    BodyContent: Text;
    ResponseText: Text;
begin
    WebMessage.CreateMessage("Http Request Type"::POST, EndpointURL, BodyContent);
    WebMessage.AddWebMessageHeader(WULWebMessageHeaderTypeNVX::"Content Header", 'Content-Type', 'application/json');
    WebMessage.AddWebMessageAuthorization(WULWebMessageHeaderTypeNVX::"Request Header", WebAuthorization);
    Commit();
    WebMessage.SendMessage(ResponseMessage);
    Commit();
    ResponseText := WebMessage.GetResponse();
end;

Web Message Headers

This record stores and manages the HTTP Headers which shall be appended to the HTTP Request.

Fields
Name	Specifies the name of the header.
Value	Specifies the value of the header.

MultiPart/Form-Data Helper

For the complex content-type MultiPart/Form-Data there is a helper codeunit for the createn of such contents added. MultiPart/Form-Data Helper

Docs / NVXWUL Web Utility Library / Tasks
MultiPart/Form-Data Helper

For the complex content-type MultiPart/Form-Data there is a helper codeunit for the createn of such contents added.

Allgemein

A multipart/form-data body can be used to send one or more files or fields. This body type can have multiple parameters with name and value. Differnt to a normal json or xml-body you can send here multiple files as a bytestream. Swagger Spezification multipart/form-data

Helper Codeunit

WULMultiPartFormDataHelperNVX

Methoden

InitBody

Prepare the codeunit instance for a new body to create. Sets the boundary to default if it is empty.

procedute InitBody()

AddKey

Add a key with type string to the multipart/form-data body.

procedure AddKey(Name: Text; Value: Text)

AddFile

Add a key with type file to the multipart/form-data body.

procedure AddFile(KeyName: Text; FileName: Text; FileInStream: InStream)

FinishBody

Finish the prepared body.

procedure FinishBody()

SetBoundary

Set a custom boundary string. This must be set before the body is initalized.

procedure SetBoundary(NewBoundary: Text)

GetBoundary

Get the set boundary.

procedure GetBoundary(): Text

GetDefaultBoundary

Get the default boundary string of the codeunit.

procedure GetDefaultBoundary(): Text

GetMultiformData

Get the prepared body after it is finished.

procedure GetMultiformData(var _TempBlob: Codeunit "Temp Blob")

GetMultiPartFormDataContentTypeHTTPHeader

Get the HTTP Header text with the boundary for the HTTP Request.

procedure GetMultiPartFormDataContentTypeHTTPHeader() MultiPartFormDataContentTypeHTTPHeader: Text

Examlpe

The example creates a multipart/form-data body with the a key names "keyvalue1" with the value "myvalue" as well as a second key with name "example_file" with the filename "example.txt" and a file content.

procedure Example(WebAuthorization: Record WULWebAuthorizationNVX; URL: Text[250]; ExampleFileInstream: InStream) ResponseText: Text;
var
    TempBlob: Codeunit "Temp Blob";
    MultiformDataHelper: Codeunit WULMultiPartFormDataHelperNVX;
    WebMessage: Record WULWebMessageNVX;
    ResponseMessage: HttpResponseMessage;
    MultiPartFormDataInStream: InStream;
begin
    Commit();

    MultiformDataHelper.InitBody();
    MultiformDataHelper.AddKey('keyvalue1', 'myvalue');
    MultiformDataHelper.AddFile('example_file', 'example.txt', ExampleFileInstream);
    MultiformDataHelper.FinishBody();

    MultiformDataHelper.GetMultiformData(TempBlob);
    TempBlob.CreateInStream(MultiPartFormDataInStream);
    WebMessage.CreateMessage(Enum::"Http Request Type"::POST, URL, MultiPartFormDataInStream);

    WebMessage.AddWebMessageHeader(Enum::WULWebMessageHeaderTypeNVX::"Request Header", 'Accept', 'application/json');
    WebMessage.AddWebMessageHeader(Enum::WULWebMessageHeaderTypeNVX::"Content Header", 'Content-Type', MultiformDataHelper.GetMultiPartFormDataContentTypeHTTPHeader());
    WebMessage.AddWebMessageAuthorization(WULWebMessageHeaderTypeNVX::"Request Header", WebAuthorization);

    Commit();
    WebMessage.SendMessage(ResponseMessage);
    Commit();
    ResponseText := WebMessage.GetResponse();
end;

Docs / NVXWUL Web Utility Library / Tasks
Test New Web Message

With this page you can test requests outgoing from business central. Here you can try to send a customized requests with defineable body, header, method and authorization.

Caution

This is a debugging tool for developers and should be used with caution. You can send with the right authorization to live endpoints and disrupt external systens.

Target, Fields
Endpoint	Specifies the endpoint which the request should be sent to.
Endpoint for Authorization	Specifies the Authorization which shoud be used for this request.
HTTP Request Type	Specifies which HTTP request type you want to use.

Payload, Fields
Payload	Specifies the payload which is sent to the endpoint.

Response, Fields
Response Reason Phrase	Specifies the http reason phrase of the received response.
Response Is Success Status	Specifies if the http request was accepted or denied.
Response Status Code	Specifies the http reason status code.

Raw Response, Fields
Raw Response	Specifies the last response received from the endpoint.

Actions

Send
Send the request to the endpoint.
Load
Load a previous send request to try to send it anew. Secret values will be omitted. Authorization cannot be copied.
Headers
Specify the headers which should be used with this request.

Docs / NVXWUL Web Utility Library / Tasks
Retention Policy

A separate retention policy has been provided for the web messages. The suggested value for the retention period is 1 month but it can be adjusted as desired.

Docs / NVXWUL Web Utility Library / Appendix
Release Notes

Would you like to know what has changed in the extension?
Below you'll find an overview of the new features and changes made in the updates. Build-Overview in DevOps

NVXWUL 2.0.21.0

as of Business Central 22
2024/06/27

Corrections
- The retention period could have been missing.

NVXWUL 2.0.20.0

as of Business Central 22
2024/06/04

Improvements
- Added New Procedure ResendWebRequest.

NVXWUL 2.0.19.0

as of Business Central 22
2024/02/21

Improvements
- TargetUrl field in WebMessage table is extended to 2048 characters.

NVXWUL 2.0.18.0

as of Business Central 22
2024/02/21

Improvements
- Added support for external OAuth Authentication.

NVXWUL 2.0.17.0

as of Business Central 22
2024/02/01

Improvements
- Error when deleting the WebMessage [function CleanUpWebMessagesOnDeleteLinkedRecord()] has been fixed.

NVXWUL 2.0.16.0

as of Business Central 22
2023/12/14

Improvements
- Added a page to customize header and body of a webmessage to send it directly out of Business Central.

NVXWUL 2.0.15.0

as of Business Central 22
2023/10/19

Modifications
- Adaptations for BC 23 compatibility.

NVXWUL 2.0.14.0

as of Business Central 17
2023/05/06

Improvements
- Added support for webservices without required authentication.

NVXWUL 2.0.13.0

as of Business Central 17
2023/04/20

Improvements
- Multipart/form-data helper codeunit added.

NVXWUL 2.0.12.0

as of Business Central 17
2023/04/12

Improvements
- Procedure AddWebMessageAuthorization added in WebMessage for the simpler adding of authorization data into the header.
- Added API Key authorization mode.

NVXWUL 2.0.11.0

as of Business Central 17
2023/02/16

Corrections
- Error when adding more than two Web Message Headers has been fixed.

NVXWUL 2.0.10.0

as of Business Central 17
2022/05/25

Improvements
- Changed sort order of page Web Message to descending.

NVXWUL 2.0.9.0

as of Business Central 17
2022/04/22

Corrections
- Error fixed with secret values of Request Headers.

NVXWUL 2.0.8.0

as of Business Central 17
2022/04/22

Improvements
- Fields and functions have been added to encrypt the credentials before sending them to the authentification endpoint.

NVXWUL 2.0.7.0

as of Business Central 17
2022/04/16

Improvements
- Improve tooltip of the action "Test Credentials and Connection". Enum WULSecretHeaderValuesNVX has been added to support extentable secret header values for custom HTTP Headers which shall be masked.

NVXWUL 2.0.6.0

as of Business Central 17
2022/03/31

Corrections
- Error when sending the first Web Message within the Try Function has been fixed.
Improvements
- The action "Test Credentials and Connection" has been added to the page "Web Authentification".

NVXWUL 2.0.5.0

as of Business Central 17
2022/02/23

Corrections
- Resolve Isolated Storage deadlock error caused by multiple session.

NVXWUL 2.0.4.0

as of Business Central 17
2022/02/19

Improvements
- Mute HTTP request error if host is not reachable.

NVXWUL 2.0.3.0

as of Business Central 17

Corrections
- Fixed Error during OAuth2 Access Token creation.

NVXWUL 2.0.2.0

as of Business Central 17

Corrections
- Identical Upgrade Tags have been inserted multiple times, which led to an error during installation.

NVXWUL 2.0.1.0

as of Business Central 17

Improvements
- Calling Web Services and API's, which require Bearer Token Authentification, is now supported.

NVXWUL 2.0.0.0

as of Business Central 17

Improvements
- On Creation Web Messages can be linked to a Record via its System Id and Table No.

NVXWUL 1.0.0.0

as of Business Central 17

Initial Version

NVXWUL Web Utility Library

Manual

☰ Contents

General

Tasks

Appendix

Docs / NVXWUL Web Utility Library / GeneralGeneral

Docs / NVXWUL Web Utility Library / TasksArbeiten mit der App

Web Authentifizierung

Authentifizierung Fields

OAuth, Fields

Basic, Fields

Bearer Token, Fields

Encryption, Fields

API Key, Fields

OAuth-external, Fields

Actions

Test Credentials and Connection

Create Test Webrequest

Web Messages

Fields

Procedures

CreateMessage

Parameters

AddWebMessageHeader

Parameter

AddWebMessageAuthorization

Parameter

SendMessage

Parameter

Web Message Headers

Fields

MultiPart/Form-Data Helper

Docs / NVXWUL Web Utility Library / TasksMultiPart/Form-Data Helper

Allgemein

Helper Codeunit

Methoden

InitBody

AddKey

AddFile

FinishBody

SetBoundary

GetBoundary

GetDefaultBoundary

GetMultiformData

GetMultiPartFormDataContentTypeHTTPHeader

Examlpe

Docs / NVXWUL Web Utility Library / TasksTest New Web Message

Target, Fields

Payload, Fields

Response, Fields

Raw Response, Fields

Actions

Send

Load

Headers

Docs / NVXWUL Web Utility Library / TasksRetention Policy

Docs / NVXWUL Web Utility Library / AppendixRelease Notes

NVXWUL 2.0.21.0

Corrections

NVXWUL 2.0.20.0

Improvements

NVXWUL 2.0.19.0

Improvements

NVXWUL 2.0.18.0

Improvements

NVXWUL 2.0.17.0

Improvements

NVXWUL 2.0.16.0

Improvements

NVXWUL 2.0.15.0

Modifications

NVXWUL 2.0.14.0

Improvements

NVXWUL 2.0.13.0

Improvements

NVXWUL 2.0.12.0

Improvements

NVXWUL 2.0.11.0

Corrections

Docs / NVXWUL Web Utility Library / General
General

Docs / NVXWUL Web Utility Library / Tasks
Arbeiten mit der App

Docs / NVXWUL Web Utility Library / Tasks
MultiPart/Form-Data Helper

Docs / NVXWUL Web Utility Library / Tasks
Test New Web Message

Docs / NVXWUL Web Utility Library / Tasks
Retention Policy

Docs / NVXWUL Web Utility Library / Appendix
Release Notes