Build an app

Before you start

Ensure you have the following details ready.

For Connected Core application:

• Socotra Connected Core credentials as a publisher or admin. These credentials are used to integrate app with your tenant. Supported credentials flows:
  • Username and Password
  • OIDC client credentials
• Another set of Socotra Connected Core credentials to a tenant with a product deployed. These credentials are to read or modify records in this tenant. Supported credentials flows are the same as above.
• App Marketplace CLI is installed and authenticated to work with Marketplace Publish API (see CLI Authentication Reference)

For Enterprise Core application:

• Socotra Enterprise Core credentials to a tenant with a product deployed. Enterprise Core integrations supports only Personal Access Tokens . Same token will be used for integration needs and data access needs. Enterprise core admins can create unique tokens per integration, if needed.
• App Marketplace CLI is installed and authenticated to work with Marketplace Publish API (see CLI Authentication Reference)

# Install globally
npm install -g @socotra/app-cli

# or locally
npm install @socotra/app-cli

Create your listing

1. Click on Publish New App under your publish tab
   
2. Fill out required fields, including which Socotra platform this app will integrate with - Connected Core or Enterprise Core
   
3. Describe your product, company, and app offering in the about section
4. Technical details, launch instructions, & compliance details should all go under the requirements section
5. Review details and click publish.
6. After publishing an app you can either use AMP manifest generation tool to create app manifest json. Socotra's publishing tool also can generate a manifest for an app, and if it asks for app name details - they can be found on this screen too.
   

Deploy app

Create your app bundle

Code

Apps are stateless Docker containers. They will be given all the information (payloads & state) they need to use at runtime from the Marketplace platform via API.

Key requirements:

• Dockerfile - Docker container must use base OS image with amd64 architecture (Example)
• Configurable port - Must listen to a configurable port, this port will be overridden by the platform via an environment variable named SMP_PORT
• Health endpoint - The platform will ping the default /health endpoint in your container to verify health. Application must expose an endpoint /health responding to GET requests with 200 OK
• State API - Apps are stateless and event driven, state is provided by AMP on each call.
  This state can be used to differentiate inbound requests to your app; remember that a single instance of your app can be serving multiple customers that have each configured the app with their own unique settings and product schemas.
  Use settings and mapping fields, defined in the manifest, to help your app be as universal as possible and serve the widest possible audiences.

State request example

const key = req.headers["x-SMP-key"];
const response = await axios.get(`${stateApi}/state/${key}`);

State response example

{
  "settings": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "mappings": [
    {
      "productName": "string",
      "fields": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      }
    }
  ],
  "socotraApiUrl": "string",
  "tenantHostName": "string",
  "token": "string"
}

Manifest

This file defines the end-user experience when launching your app; the inputs to these values will be passed as part of state.

Key requirements:

• File Name - AMP will look for socotra-app.json at the root of your Docker image
• Socotra Core Integrations - Leverage the Socotra platform to trigger requests to your app
  • Webhooks (Core) - Receive request when certain events occur in the policy system
  • Autofill (Core) - Modify policy data when requested
  • External Rater (Core) - Return pricing information for policies
• Lifecycle Hooks - Run custom logic during different app lifecycles (ex. on install, uninstall)

Deploy your app bundle

1. Authenticate with your organizations AMP credentials

socotra-app login

# Provide Client ID and API Key

API credentials are managed in the API Keys section of your dashboard

2. API credentials are managed in the API Keys section of your dashboardBuild and test example app locally (from DotNet example)

# Build project
dotnet build

# start and build docker container
$ make dr-start-local

# test locally
$ curl -d "@src/Socotra.VinLookup/Models/AutofillPayloadExamples/ExposuresPayload.json" -H "Content-Type: application/json" -X POST http://127.0.0.1:10101/vehicleLookup

3. Deploy your container to your listing

# this cmd will increment the second digit of the version number in the `socotra-app.json`
# deploys updated version of the app to socotra marketplace
make publish-app

Deploy & Launch

1. Click Test Launch. Only the publishing organization can launch their draft apps.
2. Provide all configuration details
3. Your app is now running!