Resources for SERENEDI Users:

1. Install Prerequisites
First, set up the the ASP.NET Core 3.1 runtime. To do this, go to the website https://dotnet.microsoft.com/download/dotnet-core/3.1 and click the link for the Windows Hosting Bundle. Note that although the .NET Core Runtime 3.1.0 is shown in the diagrams, any later revision of the base .NET Core 3.1 runtimes is compatible.

a. Install ASP.NET Core 3.1.X Hosting Bundle
Run and install the executable with local administrator permissions.

2. Run the Installer
The SERENEDI Windows installer is a single MSI file, above 90 MB in size. Double-click on the file.

a. Click Next, then click on the checkbox indicating acceptance of the End-User License Agreement and click Next to choose the destination folder for SERENEDI.

b. Choose a destination folder. By default, the folder is C:\serenedi. If you’d like to choose another folder, enter it here. Otherwise, select Next.

c. Click Yes to the User Account Control pop-up. It is often minimized at the bottom of the screen an orange icon.

d. After a few moments, click Finish to complete the installation.

 3. Set Up the Database
The file C:\serenedi\db\serenediCore.sql is the SQL script that constructs the serenediCore database. Since this contains many of the critical assets needed to run SERENEDI, it is labeled the “distribution database” here in the documentation. The .sql file needs to be executed only once on the database server in order to create the database and all associated data elements. Note that each installation of SERENEDI must be linked to a dedicated serenediCore database. Since the name can be changed, multiple instances of the serenediCore database can be hosted on the same server, if necessary. There are two paths to setting up the database: one using the SQL Server Management Studio interface, and one using the command line. Only one of the following two steps should be completed:
Using SSMS: If you have SQL Server Management Studio installed on the database server, opening the .sql file using SSMS and running this file via F5 will create the database.
Using the command line:  Alternatively, if you lack SSMS, you can copy the serenediCore.sql file to the SQL Server that will be used to house the database, and execute the following command:
sqlcmd -S . -U sa -P <> -i serenediCore.sql > output.txt
The -S . can be replaced with -S \ if the SQL Server is not installed on the same operating system as SERENEDI. -U sa -P <> is used if you are using an SA account on the SQL Server; otherwise, just run this script from an account with permissions needed to make these changes.
 
a. Set Up the Connection String
Given that the database was successfully installed, SERENEDI needs to know where the database is and how to access it. This information is located in the file
C:\serenedi\bin\cnnstr.txt (assuming the default installation folder was used). The default value follows:
"SQLSERVER","Data Source=(local);Database=serenediCore;Trusted_Connection=true;"

This value will work as-is if the following conditions are met: the SQL Server is installed with the default name on the local operating system, and the account used to run SERENEDI has access to the server. If, for example, the database server is located on a separate server and under a named instance, and the SA account is used, the connection string will look more like this:

"SQLSERVER","Data Source=DBSVR\SQLEDI;Database=serenediCore;User id=sa;Password=123;"

4. Set Up the User Interface (optional)

SERENEDI uses an HTTP web browser user interface that listens on port 42000 on the local machine when SerenediService is started. The web server will ignore any connections except those originating from the same machine; this is controlled by the file on C:\serenedi\bin\urls.txt. It will direct the ASP.NET Core Kestrel engine to accept incoming connections.

To listen for connections arriving from outside the local machine, change the contents of C:\serenedi\bin\urls.txt to reflect the actual IP address of the server: http://X.X.X.X:42000.

This will listen for all incoming connections that can connect to that IP. In this case, it is mandatory to have strict firewall rules in place to authorize only the correct people to have access to port 42000 on this server.

To completely disable SERENEDI Studio, you should rename the C:\serenedi\bin\serenediStudio.dll file (for example, to _serenediStudio.dll). This will prevent SERENEDI Studio from ever launching but will have no effect on the normal operation of the rest of SERENEDI. If you wish to re-enable SERENEDI Studio, merely restore the filename to its normal name, and it will launch within a few seconds.

WARNING
SERENEDI is designed to be used on security-hardened workstations and servers containing Protected Healthcare Information (PHI). SERENEDI Studio is a development and diagnostics tools designed to give extensive access to both the server file system and the database environment; it is not security-hardened in any way. By design, it uses unencrypted HTTP connections. If external IP access is opened to the Studio interface, it is your responsibility to ensure that all PHI remains encrypted and that no PHI is transmitted across insecure lines.
5. Set Up and Start SerenediService
By default, SERENEDI sets up a background service called SerenediService with a default SYSTEM account, which runs with limited privileges. If the database connection provided in step 3c uses a fixed User ID and password, SerenediService should be able to access the serenediCore database with these credentials and it can be started without assigning a dedicated domain account. If the connection string contains Trusted Connection=true;, then SerenediService will need a domain login with access to the database server.
In either case, first start the Task Manager, click on the Services tab, and click Open Services, as follows:
Then, right-click on SerenediService and click Properties.

 

a. If the database connection contains fixed credentials, you can click Start and proceed to the next step.

b. If the database connection does not contain fixed credentials, click on the Log On tab. Click the This Account radio button, then enter the credentials of a user authorized to access the SQL Server and the serenediCore database. Enter the password twice. Click OK, and then Start. SERENEDI will use this account for all database access to the serenediCore database.

c. To verify that SERENEDI is completely installed and running, look at the C:\serenedi\pipeline folder. It should contain 10 new folders, created when you started the service, like so:

This demonstrates that the SERENEDI system is accessing the serenediCore database and processing activities normally, and that installation is complete.

1. Install Prerequisites Prior to installing, we need to set up the ASP.NET Core 3.1.X runtime for Ubuntu 18.04. Instructions for various flavors of Unix are found at https://docs.microsoft.com/en-us/dotnet/core/install/linux. Ubuntu-specific instructions are found at https://docs.microsoft.com/en-us/dotnet/core/install/linux-ubuntu. a. Install the ASP .NET Core 3.1.X runtime here:
wget https://packages.microsoft.com/config/ubuntu/18.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
sudo apt-get update; \
sudo apt-get install -y apt-transport-https && \
sudo apt-get update && \
sudo apt-get install -y aspnetcore-runtime-3.1
2. Unzip the Distribution ZIP File a. In this case, we are installing to the /opt folder. Execute the following:
sudo mkdir /opt/serenedi
b. Place the distribution ZIP file in the /opt/serenedi directory, and unzip it:
unzip *.zip
3. Set Up the serenediCore Database The database is located at /opt/serenedi/db/serenediCore.sql after the above step is completed. If you have an SQL Server instance available along with a database administrator, he or she can use the above file on the SQL Server instance to create the database. Continue setup at Step c in this case. If you have the credentials for an available SQL Server instance, but no DBA, install only the SQL Command-Line Tools in step a, skip the SQL Server installation, and continue on to step b. If you have no SQL Server instance available, you can install an SQL Express instance locally. This is suitable for developer and low-resource production roles. To install the SQL Server and the tools, follow the steps listed at this website: https://docs.microsoft.com/en-us/sql/linux/quickstart-install-connect-ubuntu. a. To actually create the database, the distribution database creation script needs to be executed on an SQL Server instance. -S . references a local database server, and -U / -P references an authorized user and password.
cd /opt/serenedi/db
sqlcmd -S . -U sa -P <> -i serenediCore.sql > output.txt
b. Next, we have to modify the connection string that SERENEDI will use to connect to this database: /opt/serenedi/bin/cnnstr.txt
"SQLSERVER","Data Source=.;Database=serenediCore;User id=sa;Password=<>;"
The data source defaults to a locally hosted SQL Server database; change that to the actual server location if it is not running locally. 4. Set Up the User Interface (optional) SERENEDI uses an HTTP web browser user interface that listens on port 5000 on the local machine when SerenediService is running. This web server will ignore any connections except those originating from the same machine; this is controlled by the file on /opt/serenedi/bin/urls.txt. It will direct the ASP.NET Core Kestrel engine to accept incoming connections. To listen for all port 42000 connections arriving from outside the local machine, change the contents of /opt/serenedi/bin/urls.txt to reflect the actual IP address of the server: http://X.X.X.X:42000. This will listen for all incoming connections that can connect to this IP address. In this case, it is mandatory to have strict firewall rules in place to allow only authorized people to access port 42000 on this server. To completely disable SERENEDI Studio, you should rename the /opt/serenedi/bin/serenediStudio.dll file (for example, to _serenediStudio.dll). This will prevent SERENEDI Studio from ever launching and completely disable the graphical user interface, but will have no effect on the normal operation of the rest of SERENEDI. If you wish to re-enable SERENEDI Studio, merely restore the filename to its normal name, and it will launch within a few seconds.

WARNING

SERENEDI is designed to be used on security-hardened servers containing Protected Healthcare Information (PHI). SERENEDI Studio is a developer and diagnostics tools designed to give extensive access to both the server file system and the database environment; it is not security-hardened in any way. By design, it uses unencrypted HTTP connections. If external IP access is opened to the Studio interface, it is your responsibility to ensure that all PHI remains encrypted and that no PHI is transmitted across insecure lines. 5. Set Up and Start the SerenediService Daemon SERENEDI is meant to run persistently in the background between system reboots. To do this, we need to have SERENEDI set up as part of systemd. a. Using a text editor, create the following file: /etc/systemd/system/serenedi.service:
[Unit]
Description=SERENEDI Service
[Service] Type=simple WorkingDirectory=/opt/serenedi/bin ExecStart=/usr/bin/dotnet serenediService.dll KillSignal=SIGINT Restart=always User=<> SyslogIdentifer=serenedi [Install] WantedBy=multi-user.target b. Next, enter the following:
sudo systemctl daemon-reload
sudo systemctl enable serenedi.service
sudo systemctl start serenedi.service
For developer/workstation installations of SERENEDI, users may leverage Microsoft’s open-source, cross-platform Visual Code Integrated Development Environment (IDE) to develop new scripts. The steps are generally the same for both Unix systems and Windows systems. Note that IDE support is limited to operating systems with a graphical user interface – command line-only installations are not supported. 1. Install the latest version of PowerShell Core 7.X Go to the page https://docs.microsoft.com/en-us/powershell/ and choose the PowerShell Core installer topic for your operating system. Make sure you are installing Power Shell Core 7.X. 2. Install Visual Code Go to the page https://code.visualstudio.com/ and follow the instructions to install it on your operating system. 3. Launch Visual Code 4. Install the PowerShell Extension Click the Extensions icon (circle, far left) and enter “powershell” in the search window (second circle, top left). Click Install. Three lines of code need to be placed at the top of every script in order to set up the SERENEDI runtime environment within Visual Code. The first line sets the active directory to the SERENEDI binary folder, the second loads the SERENEDI runtime binaries, and the third initializes the runtime and sets the Base Directory to the SERENEDI installation location. Using the Windows default location:
Set-Location C:\serenedi\bin
Import-Module -Name (Resolve-Path 'serenediAPI.dll')
sapi-InitializeSession -BaseDir 'C:\serenedi'
Using the Linux default location:
Set-Location /opt/serenedi/bin
Import-Module -Name (Resolve-Path 'serenediAPI.dll')
sapi-InitializeSession -BaseDir '/opt/serenedi'
Make sure to remove/comment out the above lines of code when releasing these scripts for the automation system.
There’s also a way to use Visual Code to help troubleshoot your scripts using events fired during production. For example, if a specific trigger generated an event that critically errored and you’re not able to immediately understand why, you have the option to load the environment registers for that completed event and step through your code line-by-line to understand how the error occurred.
 
To initialize the session for a specific event, change the third line to this:
sapi-InitializeSession -BaseDir '/opt/serenedi' -BizEventId <>

These HTML files contain the pre-made mappings for SERENEDI that represent the HIPAA Implementation Guide elements.  If the map has characters that are different colors, this indicates the map can have dynamic elements.  See the User Manual section on Chiapas Gate Intermediate Format 2 for more information on how the maps are joined to the EDI elements.

5010_270 / 5010_270_A1
5010_271 / 5010_271_A1
5010_276
5010_277
5010_277CA
5010_278_REQ
5010_278_RESP
5010_820
5010_820X
5010_824
5010_834 / 5010_834_A1
5010_835 / 5010_835_A1
5010_837I / 5010_837I_A1 / 5010_837I_A2
5010_837P / 5010_837P_A1
5010_999_A1

Resources for ORACLE OCI Users

(Oracle Cloud Only)

INSTALLATION
SERENEDI is installed in three phases: Prerequisites, Main Install, and Activation.

The Prerequisites phase sets up the Ubuntu 20 instance to have the secure GUI necessary for the Visual Studio Code environment as well as the serenediStudio Web App. No external firewall ports are opened for this process; all access still requires the Oracle Instance SSH private key using a VNC port that is opened with a “bridge” on the client side.

The Main Install phase installs all of the components necessary for SERENEDI, and creates the SERENEDI distributions folders. To complete this step, the end-user must set up a valid Oracle connection string (and possibly the wallet for ADW/ATP Autonomous databases) and successfully test it from the command-line.

The Activation step deploys the SERENEDI distribution database to the Oracle server and activates the SERENEDI service.  This completes the installation.

Prerequisites

a. Create an instance using the pre-defined Oracle-supplied Canonical Ubuntu 20 image. Do not choose the minimal installation. When configuring the Boot Volume, make sure to select the “Use In-Transit Encryption” so that all traffic to and from the CPU to the boot volume remains encrypted end-to-end. Make sure download the SSH keys.

You can use most shapes that provide at least 8GB of RAM or above. Note that if you are installing an evaluation instance of SERENEDI, it will limit utilization to a maximum of four cores.

b. Log in to the instance using a terminal that allows binary file uploads/downloads. The SSH terminal SmarTTY is one good option that is freely available.

c. Upload the “install.zip” file to the default ubuntu account.

d. Enter the following:

sudo apt install unzip
unzip install.zip
cd install
chmod +x *.sh
sudo ./setup01.sh

e. The unattended setup script will take approximately half an hour to run on a single core instance. It will automatically reboot the instance when the script completes.

f. After the system reboots and you reconnect your terminal session, you will need to set up the VNC password.

Enter the following:

vncpasswd

g. Enter a password twice to set the VNC password. The password is limited to 8 characters.

h. Enter the steps to enable and start the VNC server:

sudo systemctl enable vncserver@1
sudo systemctl start vncserver@1

i. Next, you will need to enable access to the local 5901 port on your instance via an SSH bridge. This ensures that all VNC/GUI traffic is using secure encryption. Type the following on your local workstation, replacing the ssh.key with the path and filename of the private SSH key you downloaded when creating your Ubuntu 20 instance, and at the end place the IP of the OCI Instance:

ssh -i <<ssh.key>> -L 61000:localhost:5901 -C -N -l ubuntu <<IP of OCI Instance>>

j. You will be prompted to say “yes” or “no” when shown the SSH signature of the OCI instance; select Yes.

k. Next, you will need to launch a VNC client (such as the freely available TightVNC client) and open the following location:
localhost:61000

l. You should be prompted for the password you entered in the step above. If everything is successful, you will see the green Ubuntu Mate desktop, and a single Visual Studio Code icon.

m. Launch Visual Studio Code, and wait for it to launch. Then, press Ctrl-Shift-X to go to the Extensions Search pane, and type in “powershell” and enter.

n. The top result should be “PowerShell” from Microsoft. Click on it, and then in the right pane, click “Install”.

This completes installing the Prerequisites necessary to use the serenediStudio GUI and Visual Studio Code functionality of SERENEDI.

a. Run the following:

sudo ./setup02.sh

b. Create the schema for the SERENEDI Distribution database by logging into your Oracle database with administrator privileges and execute the following. Note that the schema name serenedi is not hard-coded; you can substitute any schema name you wish. Enter the following:

CREATE USER serenedi IDENTIFIED BY <>;
GRANT CREATE SESSION TO serenedi;
GRANT DWROLE TO serenedi;
GRANT CREATE TABLE TO serenedi;
GRANT UNLIMITED TABLESPACE TO serenedi;

GRANT DWROLE is especially for ATP/ADP Autonomous cloud databases. For other databases, you may replace it with:

GRANT ALL PRIVILEGES TO serenedi;

Next, create a new connection that uses the above user and password, and execute the database script.

Set up the Connection String
For ADP/ATP Oracle Autonomous Databases:
Download the wallet.zip file for the connection and unzip the contents to /opt/serenedi/bin/wallet.
Then, edit the existing file within /opt/serenedi/bin/cnnstr.txt:

"ORACLE","User id=serenedi;Password=<>;Pooling=False;Data Source=<>;"

The data source will depend on your ADW/ATP instance, and what level of utilization priority you wish to assign.

For Oracle Databases:
For EZ Connect database connections, edit the /opt/serenedi/bin/cnnstr.txt as follows:

"ORACLE","Data Source=<>:1521/xepdb1;DBA Privilege=SYSDBA;Pooling=False;User Id=serenedi;Password=<>;"

In this example, we are using the EZ Connect specification to specify the Oracle Domain, the default port (1521), and the service being used (xepdb1), followed by the user name and password information.
For other examples of Oracle connection strings, see:
https://www.connectionstrings.com/oracle-data-provider-for-net-odp-net/
Note that the connection string needs to be in the second set of quotes, and the first set of quotes is fixed with “ORACLE”.
To test the connection, run the following:

cd /opt/serened/bin
dotnet SERENEDI2.dll TESTDB

If the return result is “DATABASE: OK” then the database connection is valid, and this phase of installation is complete.

a. To create the SERENEDI Schema and complete the installation process, run the following:

sudo ./setup03.sh

To immediately test that the installation is successful, enter:

dotnet SERENEDI2.dll LICENSE