> For the complete documentation index, see [llms.txt](https://developer.sahamati.org.in/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.sahamati.org.in/sahamatinet-agent-sna/integration-guide/step-by-step-integration.md).

# Step-by-Step Integration

Follow these steps to integrate your AA service with SNA. The integration is designed to be minimal.

The AA application communicates with SNA via HTTP APIs. Sahamati will share a library, snalib, that AAs can use to set up the interface with SNA and perform the API calls.

### Step 1: Deploy SNA to your cluster

Deploy the latest version of SNA in your environment. SNA can be deployed in either of two ways:

* **Helm chart:** for REs running Kubernetes.
* **Docker:** for REs running containers without Kubernetes.

Refer to [Deploying SNA](/sahamatinet-agent-sna/integration-guide/deploying-sna.md) for detailed deployment instructions.

### Step 2: Add snalib to your service

Include the snalib library in your AA service code. The library is available for Node, Go, dotnet, and Java on Sahamati's GitHub. Refer to [SNA Library (snalib)](/sahamatinet-agent-sna/integration-guide/sna-library-snalib.md) for integration steps.

#### Step 3: Set up a connection with SNA

During AA application initialization, call the snalib function to initialize the connection to SNA.

#### Step 4: Instrument your AA-FIP interface

Call the `sna.dispatch()` method at each of the 4 AA-FIP integration points (A, B, C, D):

* **Point A (requestOut):** Call sna.dispatch() before sending a request to a FIP, with the required parameters.
* **Point B (responseIn):** Call sna.dispatch() after receiving a response from a FIP, with the required parameters. If a Point A call was made to SNA, ensure a matching Point B call is made. Handle all cases, including client failures, server timeouts, and connection failures.
* **Point C (requestIn):** Call sna.dispatch() when your AA service receives an incoming notification from a FIP, with the required parameters.
* **Point D (responseOut):** Call sna.dispatch() after your AA service sends a response back to a FIP, with the required parameters.

> 📌 **Already integrated at points A–D?** Update your existing calls to include the additional attributes (`addlAttr`) now required on the AA-FIP interface, such as `eventTime`. See Step 6.

#### Step 5: Instrument your AA-FIU interface

Call the same `sna.dispatch()` method at each of the 4 AA-FIU integration points (E, F, G, H):

* **Point E (requestOut):** Call sna.dispatch() before sending a request to an FIU, such as a consent notification, FI notification, or heartbeat.
* **Point F (responseIn):** Call sna.dispatch() after receiving a response from an FIU. If a Point E call was made to SNA, ensure a matching Point F call is made. Handle all cases, including client failures, server timeouts, and connection failures.
* **Point G (requestIn):** Call sna.dispatch() when your AA service receives a request from an FIU, such as a consent, consent fetch, FI request, or FI fetch.
* **Point H (responseOut):** Call sna.dispatch() after your AA service sends a response back to an FIU.

#### Step 6: Send additional attributes

For each `sna.dispatch()` call, on both interfaces, include the additional attributes (`addlAttr`) that apply to that API:

* `eventTime` is required on every call.
* `consentTypes` is required on FI/request calls.
* Other attributes apply to specific APIs, and some are optional.

If you prefer not to share the encrypted FI payload with SNA, you can redact the `encryptedFI` field in FI/fetch responses and send its length as `fiFetchEncDataLen` instead.

For details, see Additional Attributes (addlAttr).

> 📌 SNA is designed to be non-blocking and has minimal performance impact. All aggregation is done asynchronously inside the SNA agent. It is not done in your service.

#### Anomalous FIP behaviour

<table><thead><tr><th width="95.66668701171875">Case #</th><th width="143.6666259765625">Name</th><th width="239.9998779296875">Description</th><th>AA Action</th></tr></thead><tbody><tr><td>1</td><td>Server side send error</td><td>AA client informs SNA about a request to FIP. AA fails to connect to FIP, due to server down at FIP.</td><td>AA report httpStatus "-1" to SNA</td></tr><tr><td>2</td><td>Client side send error</td><td>AA client informs SNA about a request to FIP. AA fails to connect to FIP due to client side error</td><td>AA report httpStatus "-2" to SNA</td></tr><tr><td>3</td><td>FIP signature issue</td><td>AA sent a request to FIP. FIP sends 200OK in the response. But AA finds that the x-jws-signature is invalid</td><td>AA report httpStatus "701" to SNA, instead of 200</td></tr><tr><td>4</td><td>FIP payload format issue</td><td>AA sent a request to FIP. FIP sends 200OK in the response. But AA finds that the data format is invalid.</td><td>AA report httpStatus "702" to SNA, instead of 200</td></tr><tr><td>5</td><td>FIP payload content issue</td><td>AA sent a request to FIP. FIP sends 200OK in the response. But AA finds that the data content is wrong.</td><td>AA report httpStatus "703" to SNA, instead of 200</td></tr></tbody></table>

### Step 7: Configure the SNA endpoint

Ensure your SNA deployment is configured with the correct Sahamati endpoint.

### Step 5: Validate in UAT

Before deploying to Production, validate the integration in your UAT environment:

* Confirm that SNA is running and healthy in the cluster.
* Trigger a few AA-FIP API calls and a few AA-FIU API calls, and verify that SNA is receiving the data from both interfaces.
* After 10 minutes, check with Sahamati's team to confirm that metric payloads are being received at the UAT endpoint.
* Review the response from the endpoint for any validation errors or warnings.

### Step 6: Deploy to Production

Once UAT validation is complete, deploy SNA to your Production cluster and point it at the Production SLA endpoint.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.sahamati.org.in/sahamatinet-agent-sna/integration-guide/step-by-step-integration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.