# Reference Application Tutorial
source: https://developer.mastercard.com/commercial-event-notifications/documentation/reference_application_tutorial/index.md

This tutorial guides you through the steps to download, configure, build and execute a Java reference application that implements an end-to-end flow of the Commercial Event Notifications use cases.

The application will help you to create your own application to integrate with the API, understand how each API call is structured and to analyze responses received from the service.

The application functionality is structured as a series of tests that you can run to exercise the complete API functionality in a logical manner.

The application is split into two parts - a client and a server. The client application implements all the API calls that you can make to the API.
The server application is an example of a service that you can instantiate to receive notifications from the Commercial Event Notifications service.

## List of Tests - API Client {#list-of-tests---api-client}

|         Type          |                                                                                                            Tasks Performed                                                                                                            |
|-----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| FieldMapping API Test | Retrieves the field mappings to create a subscription                                                                                                                                                                                 |
| Subscription API Test | * Creates a new subscription with a null specification and with a filter specification * Updates existing subscriptions * Deletes an existing subscription * Retrieves all subscriptions * Retrieves a subscription for a specific ID |
| Notification API Test | * Retrieves notifications using a start and end date * Retrieves notifications using a start and end date and subscription names * Retrieves notifications using a start and end date and subscription names and push status          |

## Functionality - Server {#functionality---server}

The server application runs as a spring boot service, listens for notification messages and logs them.

## Prerequisites {#prerequisites}

The following prerequisites are needed to successfully execute the reference application components.

1. Working installations of the following software:

2. Java 8

3. Maven, to build your application and to download dependencies

4. Optionally, an Integrated Development Environment (IDE) of your choice

5. Your Maven environment must have permission either locally or to a remote repository to download the required open source libraries:

   1. Mastercard Developer OAuth Signer v1.2.4
   2. org.openapitools v3.3.4
   3. OKHttp v2.7.5
   4. Junit Jupiter v5.5.2
   5. Assert-j v3.14.0

The following steps guide you through setting up the reference application. The client and the server applications are contained in separate folders in a single zip file:

* `event-notification-openapi-java-client` for the client referred to as `[client-folder]` below
* `event-notification-sample-java-server` for the server referred to as `[server-folder]` below

The top-level folder for each application contains a readme that also describes the setup steps for that application.

Step 1 below describes how to download the zip file containing both client and server applications. Steps 2 through 5 walks through configuring and running the client application.
Step 6 is an optional step to run the server application.

## Step 1: Download and Extract the Reference Application Package {#step-1-download-and-extract-the-reference-application-package}

1. To download, click [event-notification-reference-app.zip](https://static.developer.mastercard.com/content/commercial-event-notifications/swagger/event-notification-reference-app.zip) (64KB).
2. Extract the downloaded file to a folder of your choice.

## Step 2: Get credentials for the Client Reference Application {#step-2-get-credentials-for-the-client-reference-application}

Obtain a consumer key and a sandbox keystore file that will authenticate your instance of the application to the service.

To get credentials:

1. Complete the [Getting Started](https://developer.mastercard.com/commercial-event-notifications/documentation/quick-start-guide/index.md) procedure to obtain a sandbox consumer key and a keystore file.
2. Starting from the top-level folder of the client application, go to the `[client-folder]/src/test/resources` location and add the *PKCS#12 keystore* file that you obtained through Mastercard Developers.
3. Share your consumer key with your Mastercard representative and await confirmation that the key has been configured in the Event Notifications system.

Note: If you do not have a contact at Mastercard, click 'Get Help' on the [Support](https://developer.mastercard.com/commercial-event-notifications/documentation/support/index.md) page to request that someone contact you to discuss the onboarding process.

## Step 3: Update Properties for the Client Reference Application {#step-3-update-properties-for-the-client-reference-application}

Before running the client tests, update the configuration file for the following properties:

1. Go to the `[client-folder]/src/test/java/tests/utils` location and open the config.java file.
2. Update the following properties:

|     Properties     |                                                                                                          Description                                                                                                           |
|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| consumerKey        | Update the consumer key from [Step 2](https://developer.mastercard.com/commercial-event-notifications/documentation/reference_application_tutorial/index.md#step-2-get-credentials-for-the-client-reference-application)       |
| signingKeyFilePath | Location of the keystore file from [Step 2](https://developer.mastercard.com/commercial-event-notifications/documentation/reference_application_tutorial/index.md#step-2-get-credentials-for-the-client-reference-application) |
| BASE_PATH          | Location to the sandbox environment                                                                                                                                                                                            |

## Step 4 Build the Client Reference Application {#step-4-build-the-client-reference-application}

To build the reference application:

1. If using an IDE, import the client top-level folder into your IDE with the pom file as the base for the project.
2. Either using your IDE, or through the command line, run Maven `clean` and `install` goals to:

* Download OpenAPI Generator Plugin, which generates an API client from the Event Notification API specifications.
* Download all dependencies that the API client requires.
* Generate API sources from the API specifications located at the `[client-folder]/src/test/resources` location using the downloaded OpenAPI plugin.

## Step 5: Run the Client Tests {#step-5-run-the-client-tests}

By building and installing the client reference application, the tests run automatically. You can also run the tests as a group for each file using your IDE.
The tests cannot be run individually because some tests require other tests to be completed before them.

## Step 6 (Optional): Build and Run the Server {#step-6-optional-build-and-run-the-server}

To receive push notifications from Mastercard, you can build and run the Reference Application server by following these steps:

1. Go to the `[server-folder]` and build the server by running the Maven `clean` and `install` goals.
2. Run the server by executing the following command: `mvn spring-boot:run`

The server will listen for notifications and log them as they are received. It will continue to run until interrupted.
This server will by default listen on the URL http://localhost:8080/event-notifications/notifications.

You can change the base path of `/event-notifications` by editing the setting in `~src\main\resources\application.properties`.

You can change the resource path of `/notifications` by changing the setting in `~src\main\java\event\notification\controller\NotificationController.java`

Only HTTP POST requests are accepted.

You can test the server application by performing an HTTP POST operation to this URL using a JSON payload structured as in
this notification object [example](https://developer.mastercard.com/commercial-event-notifications/documentation/parameters/notifications/notifications/index.md).

You can configure the application to listen on an external port by configuring the appropriate port forwarding settings on your firewall.
Note however that this sample application is not configured to perform authentication on clients that connect to it. Configure authentication on the server before exposing the endpoint externally.

Once your server application is developed, you can configure it to accept secure HTTP connections from Mastercard.
Mastercard uses Mutual Transport Layer Security (MTLS) to send notifications to your application.
For the connection to succeed, you must configure your application to accept MTLS connections from Mastercard
and your server must present a certificate containing a public key signed by a Certification Authority trusted by Mastercard.

Provide the URL on which your server will accept connections to Mastercard to be configured during the onboarding process.
Onboarding a URL for outbound communications has a lead time associated with it. Contact your Mastercard representative for further details about the onboarding process and lead times.

## Recap and Next Steps {#recap-and-next-steps}

After completing this tutorial, you will have:

* Gained access to a Mastercard sandbox environment.
* Built the Commercial Event Notifications reference application and configured it for your environment.
* Analyzed the construction of the event notifications API calls and their responses.
* Run the application tests and made event notifications API calls to perform various tasks.
* Optionally run the server to receive notifications from Mastercard

You can now create your own application using this reference application as a starting point.