Build an app

Before you start

Ensure you have the following:

✅ Socotra Core credentials with a product deployed

✅ App Marketplace credentials as a publisher or admin

✅ 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, keeping note of App Name, you will use this later
   
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
   

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!