NVXWUL Web Utility Library

Library App for Web Authorization and Messages.
Current Version: 2.0.19.0 as of Business Central 22.

Manual

Creation Date: 2024/04/16
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

Appendix

Release Notes
Would you like to know what has changed in the app...

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
Create Test Webrequest

Not Found

The requested topic was not found on this server.

Docs / NVXWUL Web Utility Library / Appendix
Release Notes

Would you like to know what has changed in the app? Below you'll find an overview about new features and changes that has been done in the updates. Build-Overview in DevOps

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 / TasksCreate Test Webrequest

Not Found

Docs / NVXWUL Web Utility Library / AppendixRelease Notes

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

NVXWUL 2.0.10.0

Improvements

NVXWUL 2.0.9.0

Corrections

NVXWUL 2.0.8.0

Improvements

NVXWUL 2.0.7.0

Improvements

NVXWUL 2.0.6.0

Corrections

Improvements

NVXWUL 2.0.5.0

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
Create Test Webrequest

Docs / NVXWUL Web Utility Library / Appendix
Release Notes