App types, data, and relationships

CloudBees SDM is a preview, with early access for select preview members. Product features and documentation are frequently updated. If you find an issue or have a suggestion, please contact CloudBees Support. Learn more about the preview program.

New data types, data, and relationships, can be added to System of Record via extension points in an application’s manifest.

Defining a new data type

New data types can be defined with the extension point com.cloudbees.sdm.DataType. These data types will exist in user profiles into which the application is installed. Each extension is defined as follows:

  • The extension ID must match the data type key. By default, the data type key is the lowercase snake case plural of the GraphQL type name for the data type, for example, jenkins_builds for JenkinsBuild. Snake case uses an underscore between words.

  • The schema must contain one, and only one, GraphQL type annotated with the @queryable directive. Two GraphQL queries will be created for this type: one returning a single instance of the type based on id and another returning a collection. The singular and plural of the GraphQL type name are used for these queries. jenkinsBuild and jenkinsBuilds, are example names for JenkinsBuild.

  • The schema may also contain extensions to other types and additional types used by nested object fields.

  • The key, singular, and plural arguments on the @queryable directive may be used to override the defaults e.g. to handle irregular plurals.

  • The type may also specify the @mutable directive if mutations should be generated for adding, removing and updating instances of the type.

An example might look as follows:

"extensions": { (1)
  "com.cloudbees.sdm.DataType": { (2)
    "cats": { (3)
      "schema": "type Cat @queryable { id: ID!, owner: Person @relationship, stats: Stats } type Stats { weight: Int, height: Int }" (4)
    },
    "people": { (5)
      "schema": "type Person @queryable(key: \"people\", singular: \"person\", plural: \"people\") { id: ID!, name: String! }" (6)
    }
  }
}
1 extensions is a key required by the manifest definition.
2 com.cloudbees.sdm.DataType is the extension point used by System of Record for data types.
3 cats is the data type key that matches the Cat GraphQL type name.
4 The value associated with schema key contains the GraphQL schema for the Cat type and the nested Stats type.
5 people is the data type key that matches the non-default key specified in the @queryable directive for the Person type. <6>The schema for the Person type overrides the default key and GraphQL query names.

Defining default data

The extension point com.cloudbees.sdm.Data can be used to define data to be created in user profiles into which the application is installed. The extension ID is the key to be used for the data.

The extension configuration contains two fields:

  1. type is the data type key

  2. data is the JSON data

Any subsequent updates to the data will be reflected in the installed user profiles providing that the data has not been modified via a mutation.

An example might look as follows:

"extensions": {
  "com.cloudbees.sdm.Data": {
    "tom": {
      "type": "cats",
      "data": {
        "name": "Tom"
      }
    },
    "spike": {
      "type": "dogs",
      "data": {
        "name": "Spike"
      }
    },
  }
}

Defining default relationships

The extension point com.cloudbees.sdm.DataRelationship can be used to define relationships to be created in user profiles into which the application is installed.

The extension ID is only used to identify the relationship for subsequent modification/deletion. The extension configuration contains two fields: from and to. Each of those fields contains a further two fields:

  1. type is the type key

  2. key is the data key

An example might look as follows:

"extensions": {
  "com.cloudbees.sdm.DataRelationship": {
    "tom_spike": {
      "from": {
        "type": "cats",
        "key": "tom"
      },
      "to": {
        "type": "dogs",
        "key": "spike"
      }
    }
  }
}

Webhook app extension

When creating/updating an app in SoR, to have it receive notifications via a webhook, define the following in the extensions section in the application manifest;

"extensions": {
  "com.cloudbees.sdm.Webhook": {
    "someUniqueId": {
      "webhookUrl": "http://www.webhook.url"
    },
    "anotherUniqueId": {
      "webhookUrl": "http://www.webhook_2.url"
    }
  }
}

An extension of type com.cloudbees.sdm.Webhook is included in the extensions. Within this object, is another JSON object, which must have a unique key name. Within this object, the webhookUrl on which the application wants to be called is specified.

Once the webhook URL has been set, it is sent to the application with a body of the following form:

{
  "type": "APPLICATION_INSTALLATION",
  "action": "CREATED",
  "body": {
      "account": "cloudbees",
      "appId": "xyz"
  },
  "createdAt": "2017-07-03T22:02:56+05:30"
}
  1. type is to tell whether the app is installed or registered. It can be APPLICATION_INSTALLATION or APPLICATION_REGISTRATION.

    1. APPLICATION_INSTALLATION is for a newly installed app.

    2. APPLICATION_REGISTRATION is for a newly registered app.

  2. action is to tell what has happened to the app. It can be CREATED, UPDATED or DELETED.

    1. CREATED is for an app that has been created.

    2. UPDATED is for an app that has been updated.

    3. DELETED is for an app that has been deleted.

  3. body will always have the account and appId of the new app, but this can include extra information if required.

These values are taken from the application manifest.

Each notification will have a JWT, signed by platform, in the Authorization header with scheme Webhook. A SHA-256 digest of the notification is included in the digest claim of the JWT.

A notification is not guaranteed - failed delivery attempts just result in the notification being discarded. Applications should periodically call platform to reconcile their view of registered/installed applications to allow for any missed notifications.

At the moment, notifications are sent for events in every user profile. In the future, sending notifications may be restricted to events in accounts in which the receiving app is installed.