Apps

You can extend Aidbox with custom Apps. The app can:

• define custom resources,

• define custom endpoints,

• subscribe to hooks or subscriptions.

The app is a standalone service that will work with Aidbox to implement your specific app. The app should be registered in Aidbox. Aidbox SDKs support using Apps:

Example of App resource

To define the App, we should provide the app manifest.

resourceType: App
id: myorg.myapp
apiVersion: 1
type: app
endpoint:
   url: https://my.service.com:8888
   type: http-rpc
   secret: <your-sercret>
operations: <Operations-definitions>
resources: <resources-to-be-created>

App manifest structure

Here's the manifest structure:

endpoint

In the endpoint section, you describe how Aidbox will communicate with your service:

operations

In the operation section, you define Custom REST operations as a map <operation-id>: <operation-definition> and access policy (which will be bound to this operation):

operations:
  daily-patient-report:
    method: GET
    # GET /Patient/$daily-report/2024-01-01
    # GET /Patient/$daily-report/2024-01-02
    path: ['Patient', '$daily-report', { name: 'date'} ]
  register-user:
    method: POST
    path: [ 'User', '$register' ]
    policies: 
      register-user: {  engine: allow }

Parameters:

resources

In the resources section, you can provide other resources for Aidbox in the form {resourceType: {id: resource}} using Aidbox format:

resourceType: App
resources:
  # resource type
  AccessPolicy:
    # resource id
    public-policy:
      # resource body
      engine: allow
      link:
        - {id: 'opname', resourceType: 'Operation'}

In this example, the AccessPolicy resource will be created as well as the App resource.

entities

It is a deprecated option to create custom resources via Entity/Attribute approach.

In the entities section of the App manifest, you can extend existing resources, define custom profiles, or hook into the lifecycle:

entities:

Patient: # existing resource type
  attrs:
     # here we define extension `race` for patient
     race: { extensionUrl: 'https://myapp/race', type: 'code' }
  hooks: # resource life cycle hooks
    before_create: # map of hooks <hook-id>: { config-map }
       notify_on_patient: { emails: ['[e-mail]'] }

As well as define custom resources:

entities:

User: # custom resource type
  attrs:
     email:    { type: 'email', isRequired: true }
     password: { type: 'password' }
     active:   { type: 'boolean' }
     patient:  { type: 'Reference', refers: ['Patient'] }
     settings:  
        attrs:
           theme: { type: 'string', enum: ['black', 'white'] }
  hooks:
     before_create:
        check_ldap: {}
     after_create:
        save_to_third_paty: {}
  profiles:
     user-uniq-email: 
       type: sql 
       query: SELECT true FROM "User" WHERE resource->>'email' == {{ .email }}
       message: Email is already taken

In the entities section, resources are defined in the format <resourceType> : <structure> :

entities:
  Patient: <structure>
  User: <structure>
  Payment: <structure>

Resource structure is defined by attrs keyword:

entities:

User:
  attrs:
    email: <element-definition>
    password: <element-definition>
  profiles: <profiles-definition>
  hooks: <hooks-definition>

At the root of resource definition, you can also define hooks and profiles for this resource.

Element definition will be translated into Attribute Meta-Resource and have the following properties: