Deployment on MS Windows Server 2019 (or later)
First, you need to ensure that the Internet Information Server (IIS) has already been correctly installed on the server.
Second, you also need to ensure that the ASP.NET Core Runtime from the official Microsoft site has already been correctly installed on the server.
Then you can unzip the REST-WebAPI-Core project and copy the files into a folder on the server.
Given that this is the primary interface to the trellispark framework, GreatIdeaz recommends that the endpoints for this project are placed behind a firewall and exposed via an API Manager for additional security.
To avoid a single point of failure, GreatIdeaz recommends that you install the REST-WebAPI-Core website on multiple, load-balanced web servers.
The performance of the REST-WebAPI-Core has been optimized so that for most deployments two relatively small web servers will be sufficient. As the number of users grows, you may wish to either vertically or horizontally scale the number of web servers in your load balanced pool.
Configuration – Application Pool
The IIS Application Pool for the REST-WebAPI-Core project should only contain a single website – the website will fail to run if you try to add two or more to the same pool.
The basic settings for the application pool should be:
- .NET CLR Version = No Managed Code
- Managed pipeline mode = Integrated
On the Advanced settings GreatIdeaz recommends that you set:
- Start Mode = AlwaysRunning
- Identity = A minimum permission user account with access to the folder that contains the website files and can connect to Data at Rest Record Storage database.
Configuration – Site
On the basic settings you will need to set:
- Application Pool = The IIS application pool created above
- Physical Path = Folder where you copied the REST-WebAPI-Core files
Configuration – appsettings.json
{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Information"
}
},
"AllowedHosts": "*",
"ApplicationInsights": {
"ConnectionString": "InstrumentationKey=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx;IngestionEndpoint=https://canadacentral-0.in.applicationinsights.azure.com/"
},
"ConnectionStrings": {
"TRELLIS": "Data Source=xxx.xxx.xxx.xxx;Initial Catalog=TRELLISPARK-DEV;User ID=xxxx;Password=xxxx;Min Pool Size=10;Connection Timeout=600;"
},
"Database": "MSSQLServer",
"DatabaseCommandTimeout": 400,
"AppInsightsKey": " xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx ",
"HTML2PDF_API_URL": "https://html2pdf.yourdomain.com/api/convert"
} If you wish to use Microsoft Application Insights to collect telemetry, then you will need to configure the “ApplicationInsights.ConnectionString” and “AppInsightsKey”.
You will need to set the “ConnectionStrings.TRELLIS” to be a valid connection to the Data at Rest Record Storage database. You can use either a UserID/Password or an active directory user account depending upon how you hosted the Data at Rest Record Storage database.
If you want to do HTML to PDF document conversion, then you will need to download and deploy a copy of the trellispark HTML2PDF_API website and set up the URL.
Should you choose to deploy the HTML2PDF_API project you will need a new application pool with the following settings:
- .NET CLR Version = .NET CLR Version v4.0.30319
- Start Mode = AlwaysRunning
- Identity = Minimum access user account that can read the files from the folder that contains the unzipped HTML2PDF_API website
Set up a new HTML2PDF_API site to point to the location where you copied the unzipped website files and use the new application pool.
You will also need to the MS .NET 4.8 Targeting Pack installed.
Endpoint: General Comments
All the endpoints exposed by the REST-WebAPI-Core website are called as “Post” with an “application/json” payload.
The following are common elements of the JSON payloads:
- UserGUID (input) – The GUID assigned to the user who is currently signed in and attempting to execute the request.
- SessionGUID (input)– The GUID assigned to the unique session associated with the user who is currently signed in.
- InstanceGUID/CurrentInstanceGUID (input) – The GUID assigned to the instance data that will be the focus of the request
- TargetInstanceGUID (input) – The GUID assigned to the instance that will be used as a target for the request executed against the focused instance.
- ErrorMessage (output) – An empty string if the request succeeded, otherwise contains a description of the error that occurred.
- UserMessage (output) – Generally an empty string, but when there is something that needs to be communicated back to the user about how the request was processed will contain some status text.
For all requests:
- The SessionGUID must match a valid session for the UserGUID, or the request will fail validation.
- The UserGUID must have an explicit access permission against the provided InstanceGUID/CurrentInstanceGUID.
The following subsections will outline the purpose of each of the available endpoints and the data that is sent and returned.
All endpoint requests will return one of the following status codes:
- 200 – The request processing was successfully completed, and a payload is being returned. NOTE – even if a 200 status code has been returned the request processing might have failed – the payload’s ErrorMessage should always be examined to determine the ultimate result!
- 400 – The request was badly formatted (the json model data validation failed)
- 500 – The database connection failed, or an unknown server exception occurred.
Endpoints
- AutomatedMessaging/AM/{CommandName}/{Parameters}
- Bookmark/ProcessBookmark
- Documents/GetDocument
- EventLog/LogData
- ExecuteCommand/ExecuteCommandData
- ExecuteCommand/ExecuteLocalCommandData
- ExecuteCommand/ExecuteQueuedCommand
- ExecuteSQL/ExecuteSQLData
- InstanceState/InstanceData
- Messages/ProcessMessage
- PowerBI/GetEmbedConfig
- PowerBI/RefreshDataset
- UserState/UserData
- UserState/URLParams
