SIMS Version Manager v1.0.0.6

Help & Documentation

Process Flow

1. Client Registration

Administrator creates a new Client record in the system and receives Client ID and Client Secret Key

2. D365FO Module Configuration

Client configures the D365FO module with the received credentials (Client ID, Secret Key, and API Host URL)

3. Environment Setup

Client creates Environment records for each D365FO environment (Development, Test, Production)

4. Data Synchronization

D365FO module automatically sends package version information to the system via External API

5. Version Monitoring

Administrators and clients can view and monitor package versions across all environments using the web interface

Client Setup Process

To connect your D365FO system to the SIMS Version Manager, follow these steps:

Step 1: Create Client Record

Navigate to Clients page
Go to the 'Clients' section from the main navigation menu
Click 'Add Client' button
Fill in the required information: Client ID, Client Name, ADO link, LCS_UDE project link
Save the Client record
The system will automatically generate a Client Secret Key (38-character GUID) if not provided

Step 2: Retrieve Credentials

After creating the Client record, you will receive the following credentials:

Client ID
Unique identifier for your client (editable)
This is the Client ID you entered when creating the record
Client Secret Key
38-character GUID secret key (auto-generated)
Used for authentication when making API calls - keep this secure!
API Host URL
Base URL for the API endpoint
The host URL will be provided by the system administrator. Contact your administrator to get the API Host URL for your environment. Format: http://your-host:3001/api/external/update-versions or https://your-host/api/external/update-versions

Note for Administrators: After creating a Client record, you should provide the client with:

• Client ID
The Client ID value from the record
• Client Secret Key
The 38-character secret key from the record (displayed in the Clients form)
• API Host URL
The base URL of your SIMS Version Manager installation (e.g., http://your-server:3001 or https://your-domain.com)

The full API endpoint URL will be: {API Host URL}/api/external/update-versions

Step 3: Configure D365FO Module

Configure your D365FO module with the received credentials:

Install the Version Manager module in D365FO
Deploy the custom module to your D365FO environment
Configure connection parameters
Enter the API Host URL, Client ID, and Client Secret Key in the module settings
Enable automatic synchronization
Configure the module to automatically send package version updates to the API

Forms Documentation

Clients Form

The Clients form allows administrators to manage client records in the system.

Fields:

Client ID (String 10)
Unique identifier for the client. This field is editable and visible to users.
Client Name (String 60)
Full name of the client organization
ADO Link (String 255)
Link to the Azure DevOps project for this client
LCS_UDE Project Link (String 255)
Link to the LCS UDE project for this client
Client Secret Key (String 38)
Secret key for API authentication. Auto-generated as GUID if left empty. Mandatory field.
Expiry Date (Auto-calculated)
Automatically calculated date based on environments. See 'Expiry Date Logic' section below for details.
Last Updated
Timestamp of the last update to the client record

Expiry Date Logic for Clients:

How it's calculated:

1. Priority: PROD/Production environments
First, the system looks for visible (not hidden) PROD or Production environments that have an expiryDate. It takes the minimum (earliest) expiryDate from these environments.
2. Fallback: TEST environments
If no PROD/Production environments with expiryDate are found, the system looks for visible environments with type containing 'TEST' and takes the maximum (latest) expiryDate from these environments.
3. Auto-update
The expiryDate is automatically updated when: environments are created/updated/deleted, or when environment expiryDate changes (e.g., when licenses are updated).
4. Clearing
If no suitable environments are found, the expiryDate field is cleared (set to null).

Visual Indicator: Rows with expiryDate ≤ 30 days from today are highlighted in light red (#ffebee) to draw attention to expiring licenses.

Actions:

Add Client: Click 'Add Client' button to create a new client record
Edit Client: Click the edit icon to modify an existing client
View Environments: Click the eye icon to view all environments for a client
Delete Client: Click the delete icon to remove a client (use with caution)

Environments Form

The Environments form allows you to manage client environments where D365FO packages are deployed.

Fields:

Client
The client this environment belongs to (editable dropdown)
Environment Name (String 60, Optional)
Name of the environment (e.g., Production, Test, Development)
Environment Type (String 60, Optional)
Type of environment (e.g., Production, Test, Development)
Environment URL (String 255, Optional)
URL of the environment endpoint
MS Version (String 60)
Microsoft Dynamics 365 Finance and Operations version
Platform Version (String 60)
Platform version of the environment
Expiry Date (Auto-calculated)
Automatically calculated date based on licenses. See 'Expiry Date Logic' section below for details.
Hide (Yes/No)
Hide this environment from listings (default: No)
Last Updated
Timestamp of the last update

Expiry Date Logic for Environments:

How it's calculated:

Minimum from visible licenses
The expiryDate is set to the minimum (earliest) expiryDate from all visible (hide = false) licenses for this environment that have an expiryDate.
Auto-update
The expiryDate is automatically updated when: licenses are created/updated/deleted, or when license expiryDate or hide status changes.
Clearing
If no visible licenses with expiryDate exist for the environment, the expiryDate field is cleared (set to null).

Visual Indicator: Rows with expiryDate ≤ 30 days from today are highlighted in light red (#ffebee) to draw attention to expiring licenses.

Usage:

Environments can be managed from the main Environments page or from a specific client's environments page. When creating an environment, select the client from the dropdown. The environment URL is used by the External API to identify and create/update environments automatically.

Packages Form

The Packages form displays version information for packages deployed in client environments.

Fields:

Client (Editable)
The client this package belongs to
Environment (Editable)
The environment where this package is deployed
Package Name (String 60, Editable)
Name of the package (e.g., PCM, ALOPS)
Package Version (String 60)
Version of the package (e.g., 10.2.23.2)
Package Publisher (String 60)
Publisher of the package (e.g., sis)
Expiry Date (Auto-calculated)
Automatically calculated date based on linked licenses. See 'Expiry Date Logic' section below for details.
Hide (Yes/No)
Hide this package from listings (default: No)
Last Updated
Timestamp of the last update

Expiry Date Logic for Packages:

How it's calculated:

Maximum from valid licenses
The expiryDate is set to the maximum (latest) expiryDate from all valid licenses linked to this package. A license is considered valid if: hide = false, status ≠ 'Expired', and it has an expiryDate.
Auto-update
The expiryDate is automatically updated when: licenses linked to this package are created/updated/deleted, or when license expiryDate, hide status, or status changes.
Clearing
If no valid licenses with expiryDate exist for the package, the expiryDate field is cleared (set to null).

Visual Indicator: Rows with expiryDate ≤ 30 days from today are highlighted in light red (#ffebee) to draw attention to expiring licenses.

Usage:

Packages are typically created automatically via the External API when D365FO sends version information. However, you can also manually create, edit, or delete packages from the Packages page or from a client's environments page.

Licenses Form

The Licenses form allows you to manage software licenses for client environments and packages.

Fields:

Client (Required)
The client this license belongs to
Environment (Required)
The environment where this license is used
Package Name (Optional)
The package this license is associated with. Can be selected from a lookup of packages available for the selected client and environment.
License Name (String 60, Required)
Name of the license (e.g., Enterprise License)
Expiry Date (Date, Optional)
Date when the license expires
User Count (Integer, Optional)
Number of users covered by this license
Status (String 10, Optional)
Status of the license (e.g., Active, Expired)
Hide (Yes/No)
Hide this license from listings (default: No). Hidden licenses are not included in expiryDate calculations for environments and packages.
Last Updated
Timestamp of the last update

Expiry Date Logic for Licenses:

How it affects other entities:

Environment expiryDate
When a license is created/updated/deleted, the environment's expiryDate is automatically recalculated as the minimum expiryDate from all visible (hide = false) licenses for that environment.
Package expiryDate
If a license is linked to a package (via PackageName), the package's expiryDate is automatically recalculated as the maximum expiryDate from all valid licenses (hide = false, status ≠ 'Expired') linked to that package.
Client expiryDate
When environment expiryDate changes, the client's expiryDate is automatically recalculated based on PROD/Production or TEST environments.

Usage:

Licenses can be managed from the main Licenses page or from a specific client's licenses page. When creating a license, select the client and environment. The package can be optionally linked. Licenses can also be imported via the External API using the EnvLicenses section.

All in One Form

The "All in One" form provides a comprehensive view of all clients, environments, and packages in a single table.

Features:

Unified View
See all data from clients, environments, and packages in one place
Advanced Filtering
Filter by any column using column filters or global search
Sorting & Grouping
Sort by any column or group data by multiple columns
State Persistence
Your filters, sorting, grouping, and pagination are saved and restored on next visit
Export to CSV
Export filtered and sorted data to CSV file using the Export button

Displayed Fields:

Client ID, Client Name, Environment Name, Environment Type, MS Version, Platform Version, Package Name, Package Version, Package Publisher, Expiry Date, Last Updated

Expiry Date in All in One:

The Expiry Date column displays the expiryDate from the Package entity. Visual Indicator: Rows with expiryDate ≤ 30 days from today are highlighted in light red (#ffebee) to draw attention to expiring licenses.

Expiry Date Logic Summary

The system automatically calculates and maintains expiryDate fields across different entities based on license information. This provides a comprehensive view of license expiration dates at different levels of the hierarchy.

Calculation Hierarchy

The expiryDate flows from licenses up through the hierarchy:

1. Licenses (Source)
Licenses have a direct expiryDate field that can be set manually or imported via API.
2. Packages (From Licenses)
Package expiryDate = Maximum expiryDate from all valid licenses (hide = false, status ≠ 'Expired') linked to that package.
3. Environments (From Licenses)
Environment expiryDate = Minimum expiryDate from all visible licenses (hide = false) for that environment.
4. Clients (From Environments)
Client expiryDate = Minimum from PROD/Production environments, or Maximum from TEST environments if no PROD exists.

Visual Highlighting (≤ 30 Days)

All forms with expiryDate fields automatically highlight rows that are expiring soon:

Highlighting Rule
Rows with expiryDate ≤ 30 days from today (and ≥ 0 days, i.e., not yet expired) are highlighted in light red (#ffebee).
Forms with Highlighting
Clients, Environments, Packages, and All in One forms all use this visual indicator.
Purpose
This helps users quickly identify entities with licenses that are expiring soon and require attention.

Automatic Updates

The expiryDate fields are automatically recalculated when:

A license is created, updated, or deleted
A license's expiryDate, hide status, or status field changes
An environment is created, updated, or deleted
An environment's hide status or type changes
Licenses are imported via External API

Note: All calculations happen automatically in the background. You don't need to manually update expiryDate fields.

Clearing Expiry Dates

If no suitable records are found for calculating an expiryDate, the field is automatically cleared (set to null):

Environment
Cleared if no visible licenses with expiryDate exist for the environment.
Package
Cleared if no valid licenses with expiryDate are linked to the package.
Client
Cleared if no PROD/Production or TEST environments with expiryDate exist for the client.

External API Usage

The External API allows D365FO systems to automatically send package version information to the SIMS Version Manager.

Authentication

All API requests must include authentication headers:

X-Client-Name: YourClientName
X-Client-Secret-Key: your-38-character-secret-key

Endpoint: Update Versions

POST /api/external/update-versions

This endpoint creates or updates environment and package version information.

Request Body Example:

{
  "EnvUrl": "https://your-environment-url.com",
  "MSVersion": "10.0.19041.0",
  "PlatformVersion": "1.0.0",
  "EnvPackages": [
    {
      "PackageName": "PCM",
      "PackageVersion": "10.2.23.2",
      "PackagePublisher": "sis"
    },
    {
      "PackageName": "ALOPS",
      "PackageVersion": "10.2.23.2",
      "PackagePublisher": "sis"
    }
  ]
}

The system will automatically:

Validate the Client Secret Key against the Client Name
Find or create the environment by EnvUrl
Update or create package records for the environment
Update lastUpdated timestamps for packages, environments, and clients

Error Handling

If the Client Secret Key does not match the Client Name, the API will return an authentication error. Ensure that both headers are correctly set and match the values in your Client record.

D365FO Module Configuration

After receiving your credentials from the SIMS Version Manager, configure the D365FO module:

1. Module Installation

Deploy the Version Manager module
Install the custom module in your D365FO environment
Verify module activation
Ensure the module is active and accessible in your environment

2. Connection Configuration

Configure the following parameters in the module settings:

API Host URL
Base URL for the SIMS Version Manager API
Example: http://your-host:3001/api/external/update-versions
Client Name
Your Client Name from the SIMS Version Manager
Must match exactly with the Client Name in your Client record
Client Secret Key
Your 38-character Client Secret Key
Keep this secure and never expose it in client-side code

3. Automatic Synchronization Setup

Enable automatic synchronization
Configure the module to send package version updates automatically
Set synchronization schedule
Define when and how often to send updates (e.g., daily, on package deployment)
Configure batch settings
Set the number of packages to include in each API request

4. Testing the Connection

Test API connection
Use the module's test function to verify connection to the API
Send test data
Manually trigger a synchronization to verify data is being sent correctly
Verify in SIMS Version Manager
Check the SIMS Version Manager interface to confirm data is being received

Adding Data - Manual and Automatic

Data can be added to the system in two ways: manually through the web interface or automatically via the External API.

Adding Clients

Manual Creation via Web Interface:

1. Navigate to the Clients page
Go to the 'Clients' section from the main navigation menu
2. Click 'Add Client' button
Fill in the required fields: Client ID, Client Name, Client Type, ADO Link, LCS UDE Project Link, Client Secret Key, and optional Expiry Date
3. Click 'Save' to create the client
The system will automatically generate a Client Secret Key if not provided

Automatic Creation via External API:

Clients are automatically created when the External API receives a request with a new `X-Client-Name` header. The system will:

Create a new client if one doesn't exist with the provided name
Use the X-Client-Secret-Key header as the client's secret key
Generate a unique Client ID automatically

Adding Environments

Manual Creation via Web Interface:

1. Navigate to the Environments page
Go to the 'Environments' section or a specific client's environments page
2. Click 'Add Environment' button
Fill in the required fields: Client, Environment Name, Environment Type, Environment URL, MS Version, Platform Version, Purpose, optional Expiry Date, and Hide checkbox
3. Click 'Save' to create the environment
The environment will be associated with the selected client

Automatic Creation via External API:

Environments are automatically created when the External API receives a request with environment data. The system will:

Find or create the environment based on EnvUrl and optional EnvName
Associate it with the client identified by X-Client-Name header
Update environment details if MSVersion, PlatformVersion, or Purpose are provided
Create a new environment if one doesn't exist for the given URL/name combination

Adding Packages

Manual Creation via Web Interface:

1. Navigate to the Packages page
Go to the 'Packages' section or a specific environment's packages
2. Click 'Add Package' button
Fill in the required fields: Client, Environment, Package Name, Package Version, Package Publisher, optional Expiry Date, and Hide checkbox
3. Click 'Save' to create the package
The package will be associated with the selected client and environment

Automatic Creation via External API:

Packages are automatically created and updated when the External API receives package data. The system will:

Create new packages if they don't exist in the environment
Update existing packages if version or publisher information changes
Delete packages that are no longer in the incoming list (sync behavior)
Associate packages with the environment specified in the request

Important: Packages are synchronized - if a package exists in the environment but is not in the incoming list, it will be deleted. Only packages that are new or have changed versions/publishers will trigger updates.

Adding Licenses

Manual Creation via Web Interface:

1. Navigate to the Licenses page
Go to the 'Licenses' section or a specific environment's licenses
2. Click 'Add License' button
Fill in the required fields: Client, Environment, optional Package, License Name, optional Expiry Date, User Count, Status, and Hide checkbox
3. Click 'Save' to create the license
The license will be associated with the selected client and environment

Automatic Creation via External API:

Licenses are automatically created and updated when the External API receives license data. The system will:

Create new licenses if they don't exist in the environment
Update existing licenses if any information changes
Delete licenses that are no longer in the incoming list (sync behavior)
Update environment expiry date based on license expiry dates
Associate licenses with packages if PackageName is provided

Important: If EnvLicenses is an empty array [], all licenses for the environment will be deleted. If EnvLicenses is omitted, existing licenses remain unchanged. Licenses can exist without packages (if PackageName is not provided or package is deleted).

Restricting Access to Azure Deployment

This section explains how to restrict access to your SIMS Version Manager application deployed on Azure VM, so that only employees from your domain can access it.

Option 1: Azure Application Gateway + Azure AD (Recommended)

The most secure and recommended approach - using Azure Application Gateway with Azure AD integration for authentication through your corporate domain.

Advantages:

Centralized authentication via Azure AD
Single Sign-On (SSO) for all domain employees
No changes required to the application
Access management through Azure AD groups
Access logging and auditing

Step 1: Register Application in Azure AD

1. Log in to Azure Portal
Open https://portal.azure.com and navigate to Azure Active Directory
2. Create New Application Registration
Go to App registrations → New registration. Name it 'SIMS Version Manager', select 'Accounts in this organizational directory only', and add Redirect URI: https://your-domain.com/oauth2/callback
3. Configure Authentication
In the created application, go to Authentication. Add Redirect URIs: https://your-domain.com/oauth2/callback and https://your-domain.com. Enable 'ID tokens' in Implicit grant
4. Create Client Secret
Go to Certificates & secrets → New client secret. Set description and expiration (recommended 12-24 months). IMPORTANT: Copy the Value immediately (shown only once). Also note the Application (client) ID from Overview

Step 2: Configure Azure Application Gateway

1. Create Application Gateway
In Azure Portal, find Application Gateway → Create. Fill in basic settings: Resource group, Name (e.g., 'sims-version-manager-gateway'), Region (same as your VM), Tier: Standard or WAF v2 (recommended for security)
2. Configure Frontend IP
Set Frontend IP configuration to Public - this will be the public IP address of your application
3. Configure Backend Pools
Add backend pool with your VM. Target type: Virtual machine, Target: Your VM, Target port: 80 or 443
4. Configure Listener
Protocol: HTTPS (recommended) or HTTP, Port: 443 (HTTPS) or 80 (HTTP). If HTTPS, upload SSL certificate
5. Configure Authentication
In Rules → HTTP Settings, add or edit setting. Set Authentication: Azure Active Directory, Client ID: from Step 1.4, Client Secret: from Step 1.4, Token Audience: same as Client ID
6. Create Routing Rule
Rule name: 'default-rule', Listener: select created listener, Backend pool: select created pool, HTTP Settings: select setting with Azure AD

Step 3: Configure DNS

Get Public IP Address
In Application Gateway → Frontend IP configuration, copy the Public IP address
Configure DNS Record
In your DNS provider, create A record: Name: your-domain.com, Type: A, Value: Public IP from Application Gateway, TTL: 3600

Step 4: Manage Access via Azure AD Groups

Create User Group
Azure Portal → Azure Active Directory → Groups → New group. Group type: Security, Name: 'SIMS Version Manager Users', add users who need access
Assign Group to Application (Optional)
In Azure AD application → Users and groups → Add user/group, select created group → Assign

Note: This option requires Azure Application Gateway (additional cost) but provides the most secure and centralized access management.

Option 2: Azure Front Door + Azure AD

Using Azure Front Door with access rules and Azure AD authentication. This option provides global CDN and DDoS protection in addition to authentication.

Advantages:

Global CDN and load balancing
Built-in WAF (Web Application Firewall)
Azure AD integration
DDoS protection

Setup Steps:

1. Register Application in Azure AD
Follow Step 1 from Option 1 to register the application and create client secret
2. Create Azure Front Door
In Azure Portal → Azure Front Door → Create. Configure frontend endpoints with your domain, backend pools pointing to your VM, and routing rules
3. Configure WAF Policy
Create or attach WAF policy with managed rules enabled for security. Configure custom rules if needed
4. Configure Azure AD Authentication
In Front Door configuration, enable Azure AD authentication using the Application (client) ID and Client Secret from Step 1
5. Configure DNS
Point your domain to the Front Door endpoint using CNAME record or Azure DNS integration

Note: This option provides global distribution and DDoS protection but requires additional cost for Azure Front Door service.

For more detailed instructions: See the complete guide in AZURE_ACCESS_RESTRICTION.md document (available in the project repository), which includes additional options such as Nginx + OAuth2 Proxy setup and IP whitelisting methods.

About & License Information

Software Owner

SIMS tech

https://sims-service.com/

vhlu@sims-service.com

For support, questions, or inquiries about this software, please contact SIMS tech using the email address above.

License Information

This software is provided for use by authorized clients and organizations. Unauthorized copying, distribution, or modification of this software is strictly prohibited.

For licensing inquiries, please contact SIMS tech at the email address provided above.