# Adapter playbook

The *Adapter playbook* provides guidance on how to integrate Spark with different AS400 applications. The diagram below shows the Spark Adapter solution architecture.

<figure><img src="/files/XqAv1cgDJPu6m52MKpS5" alt=""><figcaption></figcaption></figure>

## **General requirements**

### **Local environment**

#### Java

* Install [Java 17](https://jdk.java.net/java-se-ri/17).
* Test installation by running `java --version` on your terminal.

  <div align="left"><figure><img src="/files/kbTqPRdv08eDGITVXIva" alt=""><figcaption></figcaption></figure></div>

#### Maven

* Install [maven 3.9](https://maven.apache.org/download.cgi).
* Test installation by running `maven --version` on your terminal.

  <div align="left"><figure><img src="/files/0OsZBrS9OBPoLMBZULfH" alt=""><figcaption></figcaption></figure></div>

### **Docker container environment**

#### Docker

* Install [Docker](https://docs.docker.com/get-docker/).
* Test installation by running `docker --version` on your terminal.

  <div align="left"><figure><img src="/files/KNT5SBL5Cfk0JE4Vrr0Z" alt=""><figcaption></figcaption></figure></div>
* After installation please check the official [cheatsheet](https://docs.docker.com/get-started/docker_cheatsheet.pdf) for additional references on working with docker.

#### Docker-Compose

* Install [Docker-Compose](https://docs.docker.com/compose/install/).
* Test installation by running `docker-compose --version` on your terminal.

  <div align="left"><figure><img src="/files/5Lx5iTfeSnxUm1RzCpn4" alt=""><figcaption></figcaption></figure></div>
* After installation please check the [official documentation](https://docs.docker.com/compose/reference/) for additional references on working with docker-compose.

## **Adapter setup guides**

### **Adapter DML LifeAsia**

Adapter DML LifeAsia's API accepts a `POST` request with a `sparkModel`, excel file, and based of the file given, with the templates and copybooks will create a DML result as an API response in string format.

Here are some links and references for the Adapter DML LifeAsia.

* [Maven](https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html)
* [Sprint Boot](https://spring.io/projects/spring-boot)

#### **Populating the resources folder**

Provide and paste your copybooks and templates that are necessary, into the `resources` folder.

<div align="left"><figure><img src="/files/WjNurRrEeduPojabLPJT" alt=""><figcaption></figcaption></figure></div>

#### **Local environment setup**

**Install local jar dependencies**

```sh
cd lifeasia-adapter
sh ./install_lib.sh
cd -
```

**Build**

```sh
./mvnw clean package
```

**Run**

```sh
./mvnw spring-boot:run -pl adapter-dml
```

or via

```sh
java -jar -DADAPTER_PROPERTIES_REF=./lifeasia-adapter/conf/lifeasia-adapter.properties -DRESOURCES_FOLDER=./resources/ ./adapter-dml/target/adapter-dml-0.0.1-SNAPSHOT.jar
```

<div align="center"><figure><img src="/files/PUNATUPzm6l86w5dIrxH" alt=""><figcaption></figcaption></figure></div>

**Test**

```sh
curl -L -X POST 'http://{url}/converter/lifeasia/custom' -F 'sparkModel=@"/{path-to-file}"'
```

**Docker environment setup**

**Build**

```sh
docker build . -t adapter-dml-lifeasia
```

Please reference Docker's documentation on [build](https://docs.docker.com/engine/reference/commandline/build/).

**Run**

**Unix**

```sh
docker run -d -v ./resources:/app/resources --name adapter-dml-lifeasia-container -p 8080:8080 adapter-dml-lifeasia
```

**Windows**

```sh
docker run -d -v {path}/resources:/app/resources --name adapter-dml-lifeasia-container -p 8080:8080 adapter-dml-lifeasia
```

**Logs**

```sh
docker logs adapter-dml-lifeasia-container
```

Please reference Docker's documentation on [run](https://docs.docker.com/engine/reference/commandline/run/) and [logs](https://docs.docker.com/engine/reference/commandline/logs/).

***

### **Adapter DML Ingenium**

Adapter DML Ingenium's API accepts a POST request with a `sparkModel`, excel file, and based of the file, will create a DML result as an API response in JSON format.

Here are some links and references for the Adapter DML Ingenium:

* [Maven](https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html)
* [Sprint Boot](https://spring.io/projects/spring-boot)

#### **Local environment setup**

**Build**

```sh
./mvnw clean package
```

**Run**

```sh
./mvnw spring-boot:run -pl adapter-dml
```

or via

```sh
java -jar -DADAPTER_PROPERTIES_REF=pfadapter/conf/adapter.properties -DINGENIUM_TEMPLATE_REF=pfadapter/conf/Ingenium_Template.json ./adapter-dml/target/adapter-dml-0.0.1-SNAPSHOT.jar
```

<div align="center"><figure><img src="/files/s1yt19wvURwvpU1W2WWQ" alt=""><figcaption></figcaption></figure></div>

**Test**

```sh
curl -L -X POST 'http://{url}/converter/ingenium/custom' -F 'sparkModel=@"/{path-to-file}"'
```

#### **Docker environment setup**

**Build**

```sh
docker build . -t adapter-dml-ingenium
```

Please reference Docker's documentation on [build](https://docs.docker.com/engine/reference/commandline/build/).

**Run**

```sh
docker run -d --name adapter-dml-ingenium-container -p 8080:8080 adapter-dml-ingenium
```

**Logs**

```sh
docker logs adapter-dml-ingenium-container
```

Please reference Docker's documentation on [run](https://docs.docker.com/engine/reference/commandline/run/) and [logs](https://docs.docker.com/engine/reference/commandline/logs/).

***

### **Adapter Externaliser**

The externaliser is an adapter that provides calculations from Spark by listening for a request in the message queue from an AS400 server and providing the calculation result back to message queue as a response.

Here are some links and references for a Adapter Externaliser.

* [AS400 Secure](https://www.ibm.com/docs/en/i/7.1?topic=ssw_ibm_i_71/rzahh/javadoc/com/ibm/as400/access/SecureAS400.htm)
* [AS400 DataQueue](https://www.ibm.com/docs/en/i/7.1?topic=ssw_ibm_i_71/rzahh/javadoc/com/ibm/as400/access/DataQueue.htm)

<figure><img src="/files/LLaFXqo9imiFtBvMV7h1" alt=""><figcaption></figcaption></figure>

#### **Environment configurations**

Provide the proper values and credentials in the environment file through the .ini file, values such as the following:

* `SERVER` - AS400 System application server name.
* `AS400_USER` - AS400 System application user name.
* `AS400_PASSWORD` - AS400 System application password.
* `REQUESTQUEUE` - Request data queue.
* `RESPONSEQUEUE` - Response data queue.
* `LIBRARY` - System library name.
* `INPUTSIZE` - Maximum input size.
* `JADELEGACY` - Service API Link.
* `PROXY_IP` - Proxy's IP address, used for connection to call Spark.
* `PROXY_UID` - Proxy's identification, used for connection to call Spark.
* `PROXY_PWD` - Proxy's password, used for connection to call Spark.
* `SYNTHETIC_KEY` - Spark Authentication Key.
* `TENANT` - Spark Tenant Name.
* `SPARK_URL` - Spark excel engine service url.
* `TARGET_SERVICE_OUTPUT` - Key name mapping of the result.
* `SENTRY_DSN` - Sentry data source name.
* `SENTRY_DEBUG` - Enable sentry debug logs.

Create, use and paste your API key to the environment variable SYNTHETIC\_KEY in the `.ini` file in `/bin`. Please reference Coherent's documentation on [Authorization - API keys](/spark-apis/authorization-api-keys.md).

#### **Local environment setup**

**Build**

```sh
mvn install
```

**Run** Run Build (make sure to have the `.ini` file in the bin folder)

**Unix**

```sh
java -Dfile.encoding=Cp1252 -cp .:bin:target/classes:lib/jt400.jar:lib/gson-2.8.0.jar:lib/log4j.jar:lib/sentry-6.25.2.jar com.etc.ce400.Externaliser DQserver2.ini Externaliser
```

**Windows**

```sh
java -Dfile.encoding=Cp1252 -classpath "./bin;{path}/lib/commons-codec-1.11.jar;{path}/lib/jt400.jar;{path}/lib/log4j.jar;{path}/lib/gson-2.8.0.jar;{path}/lib/sentry-6.25.2.jar;" {path}/src/main/java/com/etc/ce400/Externaliser.java DQserver2.ini Externaliser
```

<figure><img src="/files/GL8XVBl3qB1PpyByiUYS" alt=""><figcaption></figcaption></figure>

**Test**

In AS400, access you AS400 server and enter your credentials.

<figure><img src="/files/XW4AXe8n4eC3Z5C6cJR4" alt=""><figcaption></figcaption></figure>

Enter your library.

<figure><img src="/files/P3zNw11YnDtDRDMhlyhC" alt=""><figcaption></figcaption></figure>

Enter the necessary inputs such as service name, key, tag names and values. Then press enter to continue.

<figure><img src="/files/88eo7ZKzZpMEQ1tYtzFb" alt=""><figcaption></figcaption></figure>

In the Externaliser logs will appear from the request. Wait for the response from the externaliser to display on the AS400.

<figure><img src="/files/ttPuuGEUeMKLlgNnDIxx" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/Zw9ueAG9HMewVqoMUm8b" alt=""><figcaption></figcaption></figure>

**Docker Environment Setup**

**Build**

```bash
docker build . -t adapter-externaliser
```

Please reference Docker's documentation on [build](https://docs.docker.com/engine/reference/commandline/build/).

**Run**

```bash
docker run -d --name adapter-externaliser-container -p 8080:8080 adapter-externaliser
```

**Logs**

```bash
docker logs adapter-externaliser-container
```

Please reference Docker's documentation on [run](https://docs.docker.com/engine/reference/commandline/run/) and [logs](https://docs.docker.com/engine/reference/commandline/logs/).

***

### **Adapter Transport**

Adapter Transport service API accepts POST requests using JSON format in body to create a file containing the DML result.

Here are some links and references for a Adapter Transport:

* [Maven](https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html)
* [Sprint Boot](https://spring.io/projects/spring-boot)

#### **Environment configurations**

A sample configuration file is located in `src/main/resources/application.yml`. It is a standard spring boot configuration.

#### **HTTP configuration**

A minimum configuration for HTTP server is as follows.

```yaml
server:
    port: 8080
```

#### **Spark configuration**

```yaml
spark:
    host: excel.staging.coherent.global
    tenant: adapter
    api.key: 34e5d792-a216-411e-a0c0-ee2ccd82e8be

webhook:
    context: post
```

* `host`: location of your Spark installation.
* `tenant`: name of your tenant.
* `api.key`: Spark API key.
* `context`: path of your webhook, defaults to `/post`.

#### **Adapter configuration**

```yaml
adapter:
    url: http://adapter-dml-container:8080/converter/ingenium/custom
```

* `url`: location of the adapter.

#### **Local environment setup**

**Build**

```sh
mvn clean package spring-boot:repackage
```

**Run**

```sh
java -jar ./target/adapter-transport-service.jar
```

or via

```sh
mvn spring-boot:run
```

<figure><img src="/files/1ZK5NfwTgszjDbt2Ihso" alt=""><figcaption></figcaption></figure>

**Test**

```sh
curl -L -X POST 'localhost:8080/api' -H 'Content-Type: application/json' -d '{
    "FolderName": "AdapterTest",
    "ServiceName": "WL60G",
    "EntityId": "35e15e92-bcbe-4dc1-ac79-3c19f309d67a",
    "UserAction": "PublishEngine",
    "AuditType": "ProductEngine",
    "Data": {
        "ProductName": "FRIPF",
        "EngineName": "ABSimpleSum",
        "FileName": "testoutput",
        "ProductId": "00d08b21-b710-4a44-b3f2-b90dec06d93d",
        "ServiceVersionId": "8527069b-faa8-4473-90c7-c99e6a665e83"
    },
    "Tenant": "adapter-dml",
    "RequestTimeStamp": "2023-02-24 11:00:00"
}'
```

A successful webhook/API request would output `testoutput.35e15e92-bcbe-4dc1-ac79-3c19f309d67a.dml` within the root app folder in the docker container.

#### **Docker environment setup**

**Build**

```sh
docker build --build-arg version=1.0-SNAPSHOT --build-arg artifact=adapter-transport-service . -t adapter-transport-service
```

Please reference Docker's documentation on [build](https://docs.docker.com/engine/reference/commandline/build/).

**Run**

```sh
docker run -d --name adapter-transport-service-container -p 8080:8080 transport-service
```

**Logs**

```sh
docker logs adapter-transport-service-container
```

Please reference Docker's documentation on [run](https://docs.docker.com/engine/reference/commandline/run/) and [logs](https://docs.docker.com/engine/reference/commandline/logs/).

***

## **Docker Compose**

Compose is a tool for defining and running multi-container Docker applications. With Compose, you use a YAML file to configure your application’s services. Then, with a single command, you create and start all the services from your configuration.

A sample `docker-compose` file might include multiple services such as adapter transport service, adapter dml ingenium and others.

```yml
version: "3.9"
services:
  adapter-dml-ingenium:
    container_name: adapter-dml-ingenium-container
    build:
      context: .
    ports:
      - 8081:8080
  adapter-transport-service:
    container_name: adapter-transport-service-container
    build:
      context: ../adapter-transport-service
      args:
        version: 1.0-SNAPSHOT
        artifact: adapter-transport-service
    ports:
      - 8080:8080
```

* `docker-compose build` - Build or rebuild services.
* `docker-compose up` - Create and start containers.
* `docker-compose stop` - Stop services.
* `docker-compose start` - Start services.
* `docker-compose down` - Stop and remove containers, networks.
* `docker-compose logs` - View output from containers.

Please reference the Docker Compose [documentation](https://docs.docker.com/compose/features-uses/).


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.coherent.global/integrations/adapter-playbook.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.