This article presents the AGIR global architecture, infrastructure requirements, and installation instructions. This document is mainly aimed at IT Specialists, however, if you are a SaaS client using AGIR as a cloud service, all infrastructure and installation procedures will be performed by our team.

1. AGIR global architecture

AGIR is an ASP.NET Web Application targeting .NET Framework 4.7.2 hosted on IIS (Internet Information Services). Depending on your version of Windows Server and its respective updates, you may need to manually install .NET Framework 4.7.2 on the server.

AGIR connects to a SQL Server database that needs to be attached to the respective SQL Server instance running on the server. The database server can be the same server that runs AGIR (application server) but it can be a second server, as long as it is accessible network-wise.

 ATTENTION  This diagram describes the AGIR architecture managed in SaaS mode in our data center. If you need an on-premises installation, we can implement AGIR with another design, allocating more or fewer resources depending on the intended use.

2. Software minimum requirements

Database Server

• Windows Server 2016 or higher
• MS SQL Server 2016 or higher
• Storage: 200 GB
• RAM: 32 GB
• 4 Cores

Application Server

• NET Framework 4.7.2 or higher
• IIS Server
• Web Deploy 3.6 or higher
• SQL Server Management Studio
• MS Office 2016 or higher
• LibreOffice as an alternative to MS Office
• Agir ASL Service
• Google Chrome
• Storage: 200 GB
• RAM: 16 GB
• 4 Cores

If you are running AGIR on a single server, assume a combination of both sets of requirements listed above.

3. AGIR installation on On-premises mode

 TIP   If you are a SaaS cliente operating Agir in Cloud mode, please proceed directly to chapter 4.

AGIR's initial setup is generally done by our team - Just send us the required information:

Connection Information - RDP, VPN, passwords, anything that might be relevant so our team is able to reach Application Server and or Database Server

Hostname - Hostname / IP where we can reach AGIR

SQL User (AgirMaster) - AGIR's SQL User (using our database script generator this user will be automatically created)

SQL Password - AGIR's SQL password (using our database script generator this user will be automatically created)

Email SMTP account -  AGIR will need an email configuration in order to send notifications and any other type of email communication.

In case we need to access the database directly and it is not possible due to your organization's security policy or any other reason, there might need to be some coordination between teams.

For effective, continuous support, the IQA Helpdesk Team should be able to access the database through SQL Server Management Studio using AGIR's SQL credentials. This can be done by accessing the server directly or through any other machine that has access to the server. For the initial installation, it will be required an SQL Server SA account and a Windows Administrator account. 

AGIR website deployment on IIS is done using Web Deploy on your Windows Server. Web Deploy can be installed by using this link:  Download Web Deploy.

It is crucial that you ensure end-users will be able to access the server on the website port, so they can reach and use AGIR. A good connection is essential for good performance and ultimately a pleasant end-user experience on AGIR.

We also highly suggest setting up an easy-to-remember hostname like agir.yourdomain.com and setting up SSL for the hostname on this server.

3.1 Instaling IIS and .NET Framework

Before proceeding, make sure your server meets the requirements listed above.

If IIS is not installed by default on your Windows Server, you may install it using the Add Roles and Features option accessible through Server Manager:

Please evaluate your needs from the list above as you may be hosting other applications on your server besides AGIR.

3.2 Database

Take note of the database initials you'll be using, they'll serve as the AGIR/DB identifier in several

steps. For example, if you're setting up a DEMO database, the initials will be DEMO.

3.2.1 New Database

This should be coordinated with our support team. A zip folder will be provided by our team including all the necessary files for creating your database and update/publish AGIR. For this step, we will execute the file called CREATE_BD_CLIENTENAME.sql. Execute this query in SQL Server Management Studio and your AGIR database will be ready.

3.2.2 Existing Database

If you wish to use an existing AGIR database, we suggest either restoring an existing backup or copying the database and attaching it to the new instance.

If you're unsure of the location of the database files, you can find them through SQL Server Management Studio. Right-click the database you wish to copy and select Properties. On the Files page, scroll horizontally all the way to the right and you'll see Path and File Name information.

Each SQL Server database consists of two files: mdf and ldf. In order to copy the files, you need

to take the database offline and detach it from the running instance.

After running the take offline section of the SQL script above, right-click the database, select Tasks, and then Detach. You may then proceed to copy the files to the new server using your preferred method. After copying, simply Attach the files on the new instance and bring the database online using the script above, if needed.

After copying an existing database, you may need to recreate the SQL credentials bound to that database. This is due to the fact that, even though the credentials on the context of the database may be copied along with the database, the SQL credentials on the context of the server don't exist, so they can't be used to log in, and access the database.

In this case, we recommend using SQL Server Management Studio and expanding the database > Security > Users. Delete any user that relates to AGIR (any name that starts with Agir). Do the same on the top level of the instance by expanding Security > Logins.

Recreate the credentials by right-clicking Logins and selecting New Login. Make sure you either copy the existing credentials exactly or follow the AGIR convention: AgirMaster and a strong randomly generated password.

The new login must use SQL Server authentication with none of the checkbox options checked.

Its default database must be the one it will be bound to (AgirMDB). On User Mapping, check Map on the login's respective database and assign the db_owner role membership. After pressing OK, make sure to access the properties of the newly created login and double-check if everything is set up correctly.

In the end, don't forget to update existing scripts with the new credentials if that's the case!

3.3 IIS configuration

Open IIS on your Windows Server. 

Right-click Sites and select Add Website. Input a site name like this: Agir. On the physical path, browse and create a folder for the website, like this: C:\inetpub\wwwroot\Agir. 

Select an appropriate binding if you have it ready, otherwise, you may always set the bindings later.

Install Web Deploy if you haven't already, it will be needed for the next steps.

The files needed for deployment are listed below. A zip folder will be provided by our team including all the necessary files.

SCRIPT_UPDATE_AGIRWEB.sql - This SQL script file contains changes to be made on the database in order to reflect any changes made on the development of new versions of AGIR - New tables, new columns, new defaults, (...);

AGIRWEB.zip - This is the website package, it contains all the necessary files compiled from the source code;

AGIRWEB.deploy.cmd - The Web Deploy script file generated by the Visual Studio Publish wizard;

AGIRWEB_CLIENTNAME.SetParameters.xml - This XML file will use the parameters within to deploy the application and set a connection string. Proceed to replace the placeholders as follows:

• Replace with the hostname / IP address of the SQL Server *

PUBLISH_AGIRWEB_CLIENTNAME.bat - A custom batch file that takes the files above and runs them with the appropriate parameters.

The first line calls the Web Deploy script with the necessary parameters. If deploying from a remote machine, you may need to add, between /Y and -setParamFile the following:

The second line executes the SQL script on the respective database. This way, every time AGIR is deployed, whether it is the first time or an update, the script ensures the database is also up-to-date.

Just like you did previously, please proceed to replace the placeholders on PUBLISH_AGIRWEB_CLIENTNAME.bat as follows:

• Replace with the hostname / IP address of the SQL Server *

After replacing, right-click PUBLISH_AGIRWEB_CLIENTNAME.bat  and select Run as administrator to execute the script. It should take a while, especially if this is the first time. The window should disappear when it's done executing. You may prevent it from closing, which is especially useful in case of error, by adding this line at the end:

If you wish to use an existing AGIR database, we suggest either restoring an existing backup or copying the database and attaching it to the new instance.

* Sometimes it is necessary to identify the SQL Server instance as well, e.g. SQLSERVER\YOURINSTANCE. You may read more about SQL Connection strings here: https://www.connectionstrings.com/sql-server/

3.4 ASP.NET State Service

AGIR uses ASP.NET State Service as a way of managing session states. After deploying for the first time, you should access services.msc on the server and make sure ASP.NET State Service is started and its Startup type option is set to Automatic.

 ATTENTION   It's always best to provide our team an easy way of deploying or periodically send you new versions of AGIR for deployment. Don't miss out on critical updates! Since every AGIR installation has different parameters, we recommend that you create specific folders for each AGIR website that your server is hosting. 

You may also have different copies of the same files properly identified with the initials of each AGIR installation, if you prefer. 

In terms of versioning, the way we internally manage it is adding a date tag (YYYY_MM_DD) to old AGIRWEB.zip and AGIR_DB_UPDATE.sql files, whenever there's a new version. The most recent files are kept with their original names so they're properly caught by the scripts.

3.5 SSL certificate

SasS clients will have access to an SSL certificate that ensures encryption in transit. 

On-premises clients must have an SSL certificate and have it installed on the application server. Our support team will be able to help you assign the certificate to AGIR. For this, we must proceed as follows:

1. On your WebsiteIIS dashboard click on Bindings;
2. On Site Bindings pop-up click Add;
3. Select Type as Https;
4. Insert your hostname;
5. Select your SSL certificate from the available list of certificates
6. Click OK

If you get an error message while saving, please pick the option Require Server Name Indication and try again.

4. Additional resources needed

4.1 AGIR Service

AGIR SERVICE is a Windows service that works as a polling mechanism for scheduled ASL tasks in AGIR. AGIR Service is a powerful process automation tool allowing an almost infinite level of customization.

Examples:

• Send a weekly report to a group of users
• Remind an overdue task
• Automatically change the status of a workflow based on a condition

It uses Google Chrome in headless mode on the server to open a GET endpoint of one or more AGIR URLs and run the code of the respective tasks.

In order to install and set up AGIR SERVICE, please follow these steps:

1. Install Google Chrome on the server;
2. Add Chrome to the server's Path variable to make it accessible as chrome on the command line (see Path Variable below for more information);
3. Extract AGIR SERVICE v6.zip to a dedicated folder on the server, e.g. C:\AGIR SERVICE 6;
4. Run Install AgirService6.bat as administrator on the respective folder;
5. Edit config_interval.txt with the time in milliseconds it should take for each time AGIR SERVICE checks for new tasks, depending on your needs (we recommend 180000 ms / 3 minutes);
6. Edit config_checks.txt and add URLs to be checked, one per line *;
7. Access services.msc on the server and confirm that the service has the Startup type option set as Automatic
8. Start the service, in case it isn't already running

We recommend restarting the service anytime either config_interval.txt or config_checks.txt are edited to make sure the service uses the new values.

4.1.1 Path Variable

In order to add a Chrome's path to the system's Path variable, follow these steps:

1. On Windows File Explorer, right-click This PC and select Properties

2. Select Advanced System settings

3. On the Advanced tab, select Environment Variables

4. On System Variables at the bottom, select Path and then Edit

5. Click New and paste Chrome's installation path, e.g. C:\Program Files (x86)\Google\Chrome\Application

6. Confirm that it is correctly added by running Chrome on Command Prompt or PowerShell - It should open Chrome

4.2 Active Directory / Azure AD / SAML 2.0 / OAUTH 2.0

Agir supports the integration of Users via Active Directory, Azure AD, SAM2.0, and OAUTH 2.0, both in SaaS and On-premises mode, so you have all the necessary resources to safely manage your users.

Permissions are managed internally by AGIR through individual customization or the creation of profiles and user groups.

This article explains in detail the information needed to implement these features: Active Directory / Azure AD / SAML 2.0 / OAUTH 2.0

4.3 Email

AGIR will need an email configuration in order to send notifications and any other type of communication. This email account is a typical no-reply@yourdomain.com address, its only purpose is to send email, not receiving.

Examples:

• User email notification for new tasks
• Weekly report to a group of users
• Email reminder of an overdue task

If your organization does not provide a personalized email, all notifications will be sent through our default account, typically identified as yourdomain@myagir.pt.

This article explains in detail the information needed to implement a customized email account: How to customize your email account.

4.4 MS Office for server-side PDF conversion

In order to promote the reliability of MS Office document conversion to PDF, we recommend installing MS Office on the application server. This way, documents edited on the end-user side will be converted by the application server and uploaded into Agir.

This is our recommended conversion engine. In case it is not possible for some technical reason or unavailability of MS Office, the alternatives are:

1. Use of LibreOffice (see chapter 4.5)
2. End-user side PDF conversion using the AGIR Office Add-in Legacy version (see chapter 4.7)
3. Use of a paid PDF conversion service - Convert API. Please contact our helpdesk team in case you need this to activate this service.

.

Requirements for MS Office:

• MS Office 2016 or higher, 64 bits

4.5 LibreOffice for server-side PDF conversion

If installing MS Office on the server is not possible, you may choose to use LibreOffice as a PDF conversion tool. But please be aware that conversion reliability may be lower, especially with documents containing graphic schemes, flowcharts, and other advanced Office objects.

https://www.libreoffice.org/

If you need to use this resource, please go back to the IIS Configuration, locate your Agir Application Pool > Advanced Settings >find combo Load User Profile and select True

4.6 Agir Office Web Add-in for End-users

This Web Add-in is recommended for editing documents online. The Web Add-in is validated by Microsoft and available free of charge in the Office Store as an Add-in for MS Word, MS Excel, and MS PowerPoint. 

It usually does not require administrator rights to install and is only available from the Microsoft Store. There are no installation files.

This Web Add-in is not mandatory to use. It is only recommended for users who edit documents. Without the Add-in the user will still be able to edit documents using normal download and upload operations.

Agir add-in for Office will automate the following editing processes:

1. Online editing of MS Word, MS Excel, and MS Powerpoint documents

2. Creating internal links to other AGIR documents

3. Creating internal links to document workflows

4. Creating internal links to process workflows

Using the Add-in does not require authentication. All data required for API authentication is automatically encrypted and stored in the advanced properties of your AGIR document.

Please refer to this tutorial on how to install AGIR Office Web Add-in: How to install Agir Office Web Add-in?

4.7 Agir Office Addin for end-users - Legacy version

Agir Office Add-in Legacy version has been used since 2016 as an online document editing tool. It is gradually being replaced by the new Web Add-in version described in chapter 4.6.

The scope and features are equivalent to those described in chapter 4.6., however, the installation requirements are different.

If the new Web Add-in version is not available in your organization, please install the Legacy version following this tutorial: How to install Agir Office? Installation files and instructions are fully available in this tutorial.

Requirements for Agir Office Addin - Legacy version

This tool will need direct communication to SQL Server through port 1433 in order to load and save application data.

This generally means creating an inbound rule to TCP 1433 on your Windows Server, which you can test with simple telnet from an end-user machine. You may also need to enable this protocol on SQL Server Configuration Manager, selecting the respective SQL instance and enabling TCP/IP on the required IP addresses and port 1433.

These are legacy apps that have been around even before the development stage of AGIR's web application. They mostly consist of projects targeting .NET Framework 4, as such the connection is made directly through .NET Framework Data Providers and Datasets. 

4.8 Agir-Wisibi mobile App

Agir-Wisibi App is a mobile application that integrates directly with AGIR. Fully responsive and cross-platform compatible with Android, iOS, and desktop. 

You don't need to install the App on your devices. You will only need to follow the app URL using your device browser (Chrome, Edge, Firefox, Safari).

With Agir-Wisibi you can carry out simple activities, where mobility is key:

1. Read or approve a document
2. Start a non-conformity or complaint report
3. Read and perform a task

The application does not replace AGIR in full. It was designed as a complement to AGIR for mobility.

If you wish to implement Agir-Wisibi in your processes, please contact our team as there may be a need for conversion and adaptation of your forms. The reason is simple: the processes will have to be designed assuming support for a smartphone's small screen.

Requirements for Agir-Wisibi Mobile App

If you are running Agir Wisibi App as an On-premises app you will need the requirements listed in chapter 2. In addition, .NET Core 3.1 Hosting Bundle needs to be installed.

4.9 Agir REST API

With our REST API´s you can create new processes, update data or send data to other applications in an integrated and secure way. For specific information please visit this article: Agir REST API.

5. Contacts

If you are an IT specialist supporting AGIR in your organization, please do not forget to visit our Helpdesk Center

Feel free to contact us as we're more than happy to help whenever possible.

Email: geral@iqa.pt

Phone: +351 214 036 913

If you need direct support from one of our IT Specialists contact:

pedrosilva@iqa.pt

pedropaulo@iqa.pt 

helderlopes@iqa.pt