Configure Remote Printing Using API Keys¶

To configure a remote site for printing you have to follow these steps:

Create API keys. Skip this step if you already have API keys for the remote sites.
Configure the main site. This step is not needed when using PLOSSYS CLI to create API keys.
Add the remote printer to PLOSSYS Output Engine
Install the remote site client

Create API Keys¶

This is how you create API keyfiles with PLOSSYS CLI for remote sites:

Open a Command Prompt or PowerShell.
Call PLOSSYS CLI to create API keys per remote site and save the output to a textfile. Use a batch script to create keys for multiple sites. The PLOSSYS CLI command only supports one site per call.
```
plossys security createApiKey <remoteSiteName> --insecure
```
Hint - export into a textfile

We recommend to export the created API keys into files to prevent loss. You will need this data at the remote site. If you lose the API keys generated, they can not be recovered.
```
plossys security createApiKey Alabasta --insecure > alabasta.txt
```
To export all keys into the same file use >> instead of >. This will append an existing file with the new output.

The output contains two sections. The section named with the remote site name holds the values needed to configure the client at the remote site. The section named mainland holds the values needed for configuration at the main site.

Example - create an API key for Alabasta

> plossys security createApiKey Alabasta --insecure
✓ Successfully created the security codes for 'Alabasta'
✓ {
        "Alabasta": {
            "DECRYPTION_SECRET": "09d63b8576ae85c0865d99c6386078691b8634ae825e1026f622a1d54b07263b",
            "IV": "dfbadfa64a02cc7e05f87e75f836006e",
            "API_KEY": "2098c2b400e2b0152e6f904d0fb75d9ab8da655a27a0da0f1d96b4c5ebe01c9b",
            "ENCRYPTED_API_KEY": "7f4d47950b1d5c66168f5e6c667479298c45a03c6637a5b9f48dfe6df669fa3b9d1eb1312691b8a0801ceca556d884af"
        },
        "mainland": {
            "DECRYPTION_SECRET": "6edb0f5038052bf1de7194d5cf82c89eebdf490b61405838eb1e1bb19915c6e4",
            "IV": "e392ec4455961fb551f329bf8f6c2221",
            "API_KEY": "2098c2b400e2b0152e6f904d0fb75d9ab8da655a27a0da0f1d96b4c5ebe01c9b",
            "ENCRYPTED_API_KEY": "fa20d6d6753e4e783983c48744a830776259029b4120ad17ce7fddc7fcb256015473862f558d3bd0934f4149ef357c07"
        }
    }

Caution

If you lose the API keys generated, they can not be recovered.

Hint - new API key

To create new API keys for an existing remote site, you have to delete that site first. Refer to Delete a Remote Site.

Continue with Add the Remote Printer.

Configure the Main Site¶

If you have created the API keys wth PLOSSYS CLI as described above, skip this step and continue with Add the Remote Printer. Remote sites created with PLOSSYS CLI have already been added to Consul.

Due to the complex nature of the CLIENTS key, these instructions show how to add the keys via Consul.

Keep the API keys generated for your remote sites ready. They might look like this:

Example - API keys for the remote site Alabasta

The values needed for the configuration of the mainland-checkout service are highlighted.

    {
        "Alabasta": {
            "DECRYPTION_SECRET": "09d63b8576ae85c0865d99c6386078691b8634ae825e1026f622a1d54b07263b",
            "IV": "dfbadfa64a02cc7e05f87e75f836006e",
            "API_KEY": "2098c2b400e2b0152e6f904d0fb75d9ab8da655a27a0da0f1d96b4c5ebe01c9b",
            "ENCRYPTED_API_KEY": "7f4d47950b1d5c66168f5e6c667479298c45a03c6637a5b9f48dfe6df669fa3b9d1eb1312691b8a0801ceca556d884af"
        },
        "mainland": {
            "DECRYPTION_SECRET": "6edb0f5038052bf1de7194d5cf82c89eebdf490b61405838eb1e1bb19915c6e4",
            "IV": "e392ec4455961fb551f329bf8f6c2221",
            "API_KEY": "2098c2b400e2b0152e6f904d0fb75d9ab8da655a27a0da0f1d96b4c5ebe01c9b",
            "ENCRYPTED_API_KEY": "fa20d6d6753e4e783983c48744a830776259029b4120ad17ce7fddc7fcb256015473862f558d3bd0934f4149ef357c07"
        }
    }

Open Consul.
```
https://localhost:8500
```
Select Key/Value in the left sidebar and click Create on the top right.
Create the DECRYPTION_SECRET key by entering the following path into the Key or folder field:
```
dc/home/env/service/mainland-checkout/tag/any/DECRYPTION_SECRET
```
Paste the DECRYPTION_SECRET listed at the mainland section into the Value field and save the key.

Example - DECRYPTION_SECRET in Consul
Create the CLIENTS key by entering the following path into the Key or folder field:
```
dc/home/env/service/mainland-checkout/tag/any/CLIENTS
```

Add the remote sites with their respective values for IV and ENCRYPTED_API_KEY into the Value field and save the key. Mind the JSON structure as shown below:

Example - JSON for two remote clients in CLIENTS

{
    "Alabasta": {
        "IV": "e392ec4455961fb551f329bf8f6c2221",
        "ENCRYPTED_API_KEY": "fa20d6d6753e4e783983c48744a830776259029b4120ad17ce7fddc7fcb256015473862f558d3bd0934f4149ef357c07"
    },
    "Krakoa": {
        "IV": "7d28eb5da719cf5412b4cc982184045a",
        "ENCRYPTED_API_KEY": "27028f9cd9c94913a010c75780038312caedc6a826f17d81fc68bcf36929e01bde90e46a9bf9bc405965e2657752a9fa"
    }
}

Example - CLIENTS in Consul

Add optional keys for mainland-checkout service as needed:
- AUTH_TYPE: authentication type, default: apiKey
- ISLAND_PORT: port the remote site clients can connect to, default: 2119
- LOG_LEVEL: Log level for the mainland-checkout service, default: info
- LPR_ENCODING: encoding for LPR jobs, default: win1252
- MONGO_REMOTE_SITES_URL: database URL for the remote site connections, default: mongodb://localhost:27017/spooler-remote-sites
Hint - Consul paths

To create those keys you can use the full path as listed in the reference for each key or navigate through the Consul structure and create them at the needed level. If the path is not correct, the keys will not be evaluated.
Continue with Add the Remote Printer

Add the Remote Printer¶

Creating a remote site printer is basically the same as creating a main site printer. The only difference is an additional key remoteSite.

Move the queue parameter remoteSite from the HIDDEN to the PLOSSYS tab.

Literature - easyPRIMA documentation

As of version 1.10.1, easyPRIMA comes with a preconfigured remoteSite parameter for queues as described above. If you use an older version of easyPRIMA, add the parameter manually. For more information, refer to easyPRIMA, System Description, Chapter 12 Queue Data, Add Customer-Specific Parameters.
Create a queue for the remote printer in easyPRIMA.
In the PLOSSYS Parameters tab, set the following parameters:
- Output Destination: IP address of the remote printer, for example 192.168.178.39
- External location (for remote queues only): name of the remote site, for example Alabasta
Hint - no typos

The name of the remote site has to be exactly the same as used to create the API keys and as specified in the mainland configuration.
Confirm with Apply.
Export the data to PLOSSYS Output Engine.
Continue with Install the Remote Site Client.

Install the Remote Site Client¶

The remote site installer provides the seal-island-checkout service and writes the connection details to the registry.

Keep the API keys generated for that remote site ready. You need them.

Example - API keys generated for the remote site Alabasta

The generated values needed for the configuration of the seal-island-checkout service are highlighted.

    {
        "Alabasta": {
            "DECRYPTION_SECRET": "09d63b8576ae85c0865d99c6386078691b8634ae825e1026f622a1d54b07263b",
            "IV": "dfbadfa64a02cc7e05f87e75f836006e",
            "API_KEY": "2098c2b400e2b0152e6f904d0fb75d9ab8da655a27a0da0f1d96b4c5ebe01c9b",
            "ENCRYPTED_API_KEY": "7f4d47950b1d5c66168f5e6c667479298c45a03c6637a5b9f48dfe6df669fa3b9d1eb1312691b8a0801ceca556d884af"
        },
        "mainland": {
            "DECRYPTION_SECRET": "6edb0f5038052bf1de7194d5cf82c89eebdf490b61405838eb1e1bb19915c6e4",
            "IV": "e392ec4455961fb551f329bf8f6c2221",
            "API_KEY": "2098c2b400e2b0152e6f904d0fb75d9ab8da655a27a0da0f1d96b4c5ebe01c9b",
            "ENCRYPTED_API_KEY": "fa20d6d6753e4e783983c48744a830776259029b4120ad17ce7fddc7fcb256015473862f558d3bd0934f4149ef357c07"
        }
    }

Download the installation file for the seal-island-checkout from the SEAL Systems delivery platform onto the remote site client.

Start the client installation:

Linux: If you have a YAML configuration file, save it as /opt/seal/etc/seal-island-checkout.yml. Execute the installer.

Example - seal-island-checkout.yml

env:
    SERVICE_URL: "http://localhost:3002"
    LOG_LEVEL: "debug"
    REMOTE_SITE: "Alabasta"
    MAINLAND_URLS: [MAINLAND_URLS]
    SERVICE_DISCOVERY: "cloud"
    TLS_UNPROTECTED: "world"
    DECRYPTION_SECRET: "09d63b8576ae85c0865d99c6386078691b8634ae825e1026f622a1d54b07263b"
    ENCRYPTED_API_KEY: "7f4d47950b1d5c66168f5e6c667479298c45a03c6637a5b9f48dfe6df669fa3b9d1eb1312691b8a0801ceca556d884af"
    IV: "dfbadfa64a02cc7e05f87e75f836006e"

Windows: If you have a preconfigured *.mst file for the remote site, open a command line and execute the following command to start the installer:
```
/i seal-island-checkout seal-island-checkout-x.x.x.x.msi TRANSFORMS=<island_configuration>.mst
```
Otherwise start the installer by double-clicking it.

Enter the connection data:
- API Key: Encrypted API key for the remote site
- IV: IV for the remote site
- Secret: decryption secret for the remote site
- Urls: URL of the Output Engine system, accessible from the outside
- Remote Site: name of the remote site as used to create the API key
If you used a configuration file, you only have to enter the Secret.

Hint -no typos

The name of the remote site has to be exactly the same as used to create the API keys and as specified in the mainland configuration.
Confirm with Next and start the installation with Install.

Hint - registry

The Windows installer stores the connection data in the registry at Computer\HKEY_LOCAL_MACHINE\SOFTWARE\SEAL Systems\seal-island-checkout. Note, it does not store the API key but the encrypted version of it.
To test the connection, click Open Monitor after the installation is finished or call https://localhost:3002 in your browser.

Modify the Remote Site Configuration¶

Execute the installer for the seal-island-checkout again.
Select Repair.

Hint - Windows client

When changing the seal-island-checkout on a Windows client using the Repair option, default values will be written into the registry instead of the changed data. To prevent that issue, uninstall the current client first, then install anew.

Delete a Remote Site¶

There are several ways how to delete a remote site:

Uninstall the seal-island-checkout at the client.
Edit the CLIENTS key and delete the entry for that site from the JSON value.
Delete the remote printer in easyPRIMA or change its remoteSite parameter.