MTOA Web Service Framework

The MTOA Web Service Framework makes it easier to bootstrap a Web Service Project that:

• Uses MTOA for API KEY authentication and authorization

• Has out-of-the-box integration with MTOA Web Service Capabilities

• Supports both .NET Framework and .NET Core

Initialization

The MTOA Web Service Framework needs to be initialized as follows

In Global.asax.cs 

In UnityConfig.cs

Configure the API Key in the Web.Config file

API Key Authorization

By default, the MTOA Web Service Framework authorizes API keys that are bound to the same service specified during the Web Service initialization.
For example, if the MTOA Web Service Framework has been initialized with the following call, it means that the caller application needs to be bound to the “RTMR” service for the call to be successful.

ServiceFramework.Initialize(container, rtmrServiceId);

If a Web Service needs to interact with an application that isn’t bound to that specific service (in this example rtmrServiceId), the WEBSERVICE_FRAMEWORK_ALLOWED_SERVICES Service Setting can be used to specify the service name to authorize.

By specifying this Service Setting (using the MTOA ServiceSettingAPI), the Web Service will accepts both the MTOA API KEY and the RTMR API KEY (even if our Web Service was associated with the MTOA service).

Open

Using myTC Account Nuget Packages

If you don’t have access to TC NuGet, go to:
Tools > Options > NuGet Package Manager > Package Sources and add a reference to http://nuget.tc.gc.ca/nuget.

Open

To install the myTC Account NuGet packages, right click on the project and select Manage NuGet Packages.

Once this is done, ensure that the Package source on the top right corner is set to “TC Nuget“.

Make sure Browse is selected and search for “MTOA” and install all of the packages.

Layouts

Colored Cards

Below is a sample HTML for the cards.

CSS used for the cards

1.1.1.1      Service Tiles

Below is a sample HTML

CSS

1.1.1.1      My Requests Cards

Below is a sample HTML

CSS

Main navigation bar 

In order to use the navigation bar you need create a sub folder called MainNavigationBar under the Views folder and create a file called Index.cshtml. In your Controllers folder add a new controller called MainNavigationBarController.cs.

 Note: The following section is only applicable if you’re not using the myTC Account Services Template.

Steps to add the Main Navigation Bar

Add View

Create a sub folder called MainNavigationBar and add a view called Index.cshtml. You will need to update your resource files to include the required text.

In the Index.cshtml add the following HTML:

Add Controller

Add MainNavigationController.cs

Create an action called Index and add this line at the top to have access to the view model (using WebCommon.ViewModels;) and populate the view model (see below).

Set CustomSiteMenuUrl

In your BaseController override the PopulateViewBag function and this line:

Adding the ServiceTitleBar

In the View folders in the Shared sub folder create a file called _ServiceTitleBar.cshtml.

Add the following to the partial view:

Add to view

Inside your view add the following line:

In your view model add the following property:

Inside your controller you can set the view models ServiceTitleBar property to set the Title, TitleBarButtons with associated text and links.

Wizard Control

The wizard control is used to visually display the status of each steps when filling out a form.

Steps to add the Wizard

Adding the Wizard

In the View folders in the Shared sub folder create a file called Wizard.cshtml.

Add to view

Inside your view add the following line:

Figure 3.4‑13 -  Add to view

In your view model add the following property:

Add WizardStepState

In your Models folder add an Enum called WizardStepState.

Add WizardStepViewModel

In your Models folder add a new view model called WizardStepViewModel.

Add WizardViewModel

In your Models folder add a new view model called WizardViewModel.

Add WizardController

Create a WizardController in the Controllers folder, or add the following code in your controller.

1.1.2          Survey Feedback

The survey lets you select a rating from 1 to 5 stars (this is a required field) and also add optional comments. The survey is anonymous, which means that the user’s id will not be saved in the database.

You can view an example of the survey feedback on this site: http://ncras545.tc.gc.ca:8084/eng/feedback

Steps to create a survey feedback.

Rendering 5 Star Rating Bar in your Survey Feedback involves following tasks:

Create a partial-view "_rating.cshtml" to render 5 Star Rating Bar in your Survey Feedback

a)     In above code "@model string[]"  accepts string array – this partial view expects at least two values; the first element in array must be the “name” attribute for “radio” buttons that partial view uses for “stars”

b)    Above partial view renders 5 Star Rating Bar in your Survey Feedback, as shown below:

In your controller create a POST action

Add “Resource” strings used in tooltip (meets an accessibility of 5 Star Rating Bar in your Survey Feedback)

At present partial-view (_ratings.cshtml) mentioned above, expects a “Resource” file, however as per your need you may copy following resource strings to different CSS file, in that case make sure to change above mentioned partial-view to use resource file of your choice.

French Translation for tooltip:

In case you want to get the feedback in a middle of your view you only need following

...

...

If you want a feedback in a Dialog then inside your view add the following

Copy styles in a separate css file (in this case css file is “rating.css”)

Note: Above stylesheet uses “on.svg” and “off.svg” to draw solid and hollow star

To draw stars, copy following svg files and if needed change relative path in above CSS

Content of “on.svg”

Content of “off.svg”

Either copy above styles in a view or reference a separate css file

In this case we reference above rating.css file in a view where rating bar need to be displayed

If rating bar is used in a Dialog then inside your view copy following script

Above Javascript performs following tasks:

a)     "feedbackDialog.trigger('open.wb-overlay');" opens a dialog defined (assumes you want a feedback in a dialog) with id “#feedback-screen”

b)    Monitors the input within each input in a form defined with id “#feedbackForm” (you may need to change it to suite your need)

c)     Enables “submit” button with id "saveAndContinueButton" when there is at least one input value has non-null input or if one of 5 Star rating selected

d)    Submits the content of a form defined with an id “feedbackForm” async post to whatever the “Action” defined on “feedbackForm”

e)     Closes the dialog immediately after submitting the “feedbackForm”

If rating bar is used in a regular form (not in a Dialog) along with other input elements then inside your view copy following script

1.1.1          Adding the Notices menu

Under Views -> MainNavigation, open Index.cshtml.

Add a new link item with a link for notices.

Update your resource files with “Notices” from English and “Avis” for French.

MainNavigationBarController

Under Controllers, open MainNavigationBarController.cs

In the view model add the NoticesPageUrl property and call the GetNoticesPageUrl function.

Display notices on service website

Add the code to retrieve notices of the user.

Modify the view to load the notices
Example:

1.1.1          Application user properties

To access user who’s currently authenticated you can use the CurrentUser property which is accessible in the BaseController.

1.1.2          Application Session Timeout

In you web.config you can add Session Timeouts by modifying the following section:

In this example (highlighted in yellow) after 17 minutes if inactivity a prompt will be displayed with 3 minutes of reaction to either continue or end the sessions. A logout URL. The default value for a timeout is 20 minutes.

For more information you can visit the following site:

·         https://wet-boew.github.io/v4.0-ci/docs/ref/session-timeout/session-timeout-en.html

·         https://gccode.ssc-spc.gc.ca/iitb-dgiit/sds/GOCWebTemplates/DotNetTemplates/wikis/Documentation/configurations (Under Session Timeout header)

1.1.3          Invoices

1.1.3.1      Business Object

Invoice

1.1.3.2      Manager

InvoiceManager

1.1.3.3      InvoiceManager.Add(Invoice) Method

Creates a new invoice.

In this example a new invoice is created with the values provided. The id isn’t required, as it gets generated automatically.

1.1.3.4      Parameters

Invoice (Invoice)
Business object used to get/set the values.

1.1.3.5      Returns

Task<Invoice> (Invoice)
An Invoice with all of the created invoice information.

1.1.3.6      Exceptions

MtoaException
If the add can’t be completed.
If the Service Request id is deleted or doesn’t exist.

1.1.3.7      InvoiceManager.Update(Invoice) Method

Updates an existing invoice.

In this example an existing invoice value get updated. A valid id must be provided, or no changes will be made. An existing invoice can be retrieved using the GetByNumber() or GetPaymentReference() functions.

1.1.3.8      Parameters

Invoice (Invoice)
Business object used to get/set the values.

1.1.3.9      Returns

Task<Invoice> (Invoice)
An Invoice with all of the updated invoice information.

1.1.3.10    Exceptions

MtoaException
If the update can’t be completed.
If the Service Request id is deleted or doesn’t exist.

1.1.3.11    InvoiceManager.GetByNumber(string) Method

Get an invoice by its number.

In this example an invoice is retrieved by using a number. The number must be a valid.

1.1.3.12    Parameters

Number (string)
The invoice number.

1.1.3.13    Returns

Task<Invoice> (Invoice)
An invoice with all of the information.

1.1.3.14    Exceptions

MtoaException
Invoice is not found.

ArgumentException
If the id is equal to zero.

1.1.3.15    InvoiceManager.GetByPaymentReference(string) Method

Get an invoice by its payment reference number.

public async Task<Invoice> GetByPaymentReference(string reference)

In this example an invoice is retrieved by using a number. The reference number be valid.

1.1.3.16    Parameters

Reference (string)
The invoice payment reference number.

1.1.3.17    Returns

Task<Invoice> (Invoice)
An invoice with all of the information.

1.1.3.18    Exceptions

MtoaException
Invoice is not found.

ArgumentException
If the id is equal to zero.

1.1.3.19    InvoiceManager.GetByServiceRequest(string) Method

Gets a list of invoices by service request id.

In this example a list of invoices are returned given a valid service request id. 

1.1.3.20    Parameters

ServiceRequestId (int)
The service request id.

1.1.3.21    Returns

Task<ICollection<Invoice>> (Invoice)
A collection of invoices with all of the invoice information.
Null is returned if no invoices are found.

1.1.3.22    Exceptions

ArgumentException
If the id is equal to zero.

1.1.3.23    Code sample

Add this view model to use with the controller and view.

Add this view to either create or update an invoice.

Add this controller for invoices.

1.1.4          File Attachments Upload

1.1.4.1      Domain Object

FileAttachment

Used to get or set the values of a file attachment.

1.1.4.2      FileAttachmentManager.Upload(FileAttachment) Method

Uploads a new file attachment to the database.

How to create a new file attachment. The file attachment id isn’t required, since it gets generated automatically.

1.1.4.3      Parameters

FileAttachment (FileAttachment)
Business object used to get/set the values.

1.1.4.4      Returns

Task<FileAttachment> (FileAttachment)
A FileAttachment with all of the uploaded attachment information.

1.1.4.5      Exceptions

MtoaException
If the upload can’t be completed.
If the Service Request id is deleted or doesn’t exist.

MtoaVirusScanException
If a virus is detected or any issues found during the scanning process.

1.1.4.6      FileAttachment.GetById(int) Method.

Return a file attachment by its id.

In this example a file attachment is retrieved by using its id.

1.1.4.7      Parameters

Id (int)
The file attachment id.

1.1.4.8      Returns

Task<FileAttachment> (FileAttachment)
A FileAttachment with all of the uploaded attachment information.

1.1.4.9      Exceptions

MtoaException
File attachment is not found.

ArgumentException
If the id is equal to zero.

1.1.4.10    FileAttachmentManager.GetByServiceRequest(int) Method

Returns a list of file attachments by service request id.

In this example a list of file attachments are retrieved by using a service request id. The id must be a valid.

1.1.4.11    Parameters

Id (int)
The service request id.

1.1.4.12    Returns

Task<ICollection<FileAttachment>> (FileAttachment)
A collection of file attachments with all of the file attachment information.
Null is returned if no file attachments are found.

1.1.4.13    Exceptions

ArgumentException
If the id is equal to zero.

1.1.4.14    FileAttachmentManager.Remove(int) Method

Removes a file attachment by its id.

public async Task Remove(int id)

In this example a file attachment is removed by using its id. The id must be valid.

1.1.4.15    Parameters

Id (int)
The service request id.

1.1.4.16    Exceptions

ArgumentException
If the id is equal to zero.

1.1.4.17    Large file upload configurations (.NET CORE)

By default, ASP.NET Core allows you to upload files up to 28 MB (approximately) in size.
If your application doesn’t have a web.config file. You’ll need to add one. Below is how the web.config should look like.

maxAllowedContentLength is measured in bytes. In this example the value is set to 201MB.

1.1.4.18    File names and special characters

The file name must start with a letter or a number, and can have the following special characters:

·          A space

·         ,

·         -

·         _

·         .

File extension must at least have two letters for the file extension.

This is the regular expression used to validate the file names: ^[a-zA-Z0-9][a-zA-Z0-9, \-,_\.]*\.[A-Za-z]{3,}$

1.1.4.19    Virus Scan

All files are scanned for viruses using the OSWAT MetaDefender version 5.1.2. For more information see this document.

1.1.4.20    Creating a new file attachment using model, view and controller (.NET CORE)

1.1.4.21    Adding a new file attachment view model

Create a new view model.

1.1.4.22    Adding a file attachment controller.

Create a new file attachment controller.

1.1.4.23    Adding a file attachment view (index).

Create a new file attachment view called Index to add a new file attachment List is used to view a file attachment per service requests.