Datastore

Choose the right component

Use the flowchart below to assist in choosing the appropriate component for your use case:

Component decision tree

Datastore is a Squiz Digital Experience Platform (DXP) data service product that uses blueprints (industry-standard API specifications and data model files) to:

  • Simplify storing and querying data for web applications, and

  • Facilitate the delivery of customer experiences by levering blueprints to automate backend tasks.

Prerequisites

Before you start using the Datastore component with Connect, several conditions must first be met:

  • You must install the Datastore and DXP CLI tools. Instructions can be found in the Datastore documentation.

  • Add or update your Datastore blueprint’s service. Information about how to do this can be found in the Datastore Product CLI documentation.

  • You must bundle your Datastore blueprint for Connect. Information about how to do this is in the Datastore documentation.

Credentials

Datastore OpenAPI .yml spec - Bundled file

A Squiz Datastore blueprint spec document generated by the Datastore Bundle CLI is an OpenAPI3 compliant .yml file that defines the calls that can be made to the datastore instance and all required parameters and responses for each endpoint and operation.

This file must contain a servers field with an element that includes the description Datastore production and the URL for the production instance.

Both the URL and description fields are static values and must not be changed.

JWT Payload & Secret Key

The component supports administration requests to the Datastore instance.

A secret key and JWT payload must be provided in the credential for any request that requires authorization. The key and payload are used to generate a JSON Web Token which will be passed in the header as a bearer token to authorize administrator requests.

If this box is clear, requests will be made without authentication.

The payload required is dependent on the x-datastore-acl value in the request spec. For example, if the GET request for a particular path has x-datastore-acl: jwt.isAdmin === true, then the payload would be {"isAdmin": true}.

If the GET request for another path has x-datastore-acl: jwt.userid === document.userid, then the payload would be {"userid": "<userid>"}(where the payload corresponds to the userid value from the Datastore - collection) for the request from Connect to be authorized.

Verify Credentials

Verifying credentials confirms the syntax of all the fields under credentials. It checks such things as whether a valid JSON JWT payload is provided and if a secret key is provided.

It also verifies that a valid YAML OpenAPI .yml spec file is provided and checks that it contains a servers field with a valid description and URL.

Successfully verifying the credential does not evaluate the secret key and payload for authentication, nor does it make any request using these credentials.

Triggers

This component has no trigger functions. Therefore, this component cannot be used as the first one when designing an integration flow.

Actions

Make request

Configuration fields

Path & operation

A dropdown for the path and operation combinations that are defined in the Blueprint spec document.

Don`t throw error on failed calls

Denotes whether errors should be thrown for HTTP codes in the 4xx/5xx range. If this option is selected, the error response will be emitted to the next flow step.

Split result if its an array

If selected, Connect will check if the body of the response is an array and will emit one message for each element.

Input metadata

Input metadata is dynamically populated based on the selected parameters. These are defined in https://swagger.io/docs/specification/describing-parameters/. path parameters are defined as separate fields, and requestBody as an object that should be configured by the user.

For example, Datastore Personalisation Blueprint spec path /users/{userid} and operation patch metadata is:

{
  "type": "object",
  "properties": {
    "requestBody": {
      "note": "undefined",
      "required": false,
      "type": "object",
      "viewClass": "TextAreaView",
      "title": "'Request Body - Example: {\n  'siteVisits': 10,\n  'urlParam': 'campaign-alpha',\n  'country': 'AU'\n}'"
    },
    "userid": {
      "note": "ID of the user.",
      "required": true,
      "title": "userid",
      "type": "string"
    }
  }
}

Excerpt from the spec with this operation

openapi: 3.0.2
info:
  title: Personalization Framework Blueprint
  description: For permanent storage of user traits and opted personas for the Matrix Personalization Framework.
  version: 1.0.0
  paths:
    '/users/{userid}':
      parameters:
        - in: path
          name: userid
          description: ID of the user.
          required: true
          schema:
            type: string
            example: 977a0dbb-45f9-4424-aa5a-b10b09fdbf0d
      patch:
        description: Allows a user to be updated. Required at a minimum for updating 'site visits' property on return visits.
        tags:
          - users
        operationId: updateUser
        x-datastore-acl: public
        responses:
          '200':
            description: The user info is returned for the updated user.
            content:
              application/json:
                schema:
                  $schema: 'http://json-schema.org/draft-07/schema#'
                  type: object
                  properties:
                    userid:
                      x-datastore-source: document.$id
                      description: The ID of the document.
                    optedPersona:
                      title: The persona or personas a user has opted to be part of.
                      type: array
                      items:
                        type: string
                        description: When a user opts into a persona and it's no longer calculated by evaluating the traits.
                        example: international
                    siteVisits:
                      title: Site visits
                      description: Increments on each page load of the site.
                      type: integer
                      example: 10
                      default: 1
                    urlParam:
                      title: URL parameter
                      description: The user entered the site using a specific URL parameter.
                      type:
                        - 'null'
                        - string
                      example: campaign-alpha
                    country:
                      title: Country code
                      description: 'Country code list from Maxmind so ISO standard https://dev.maxmind.com/geoip/legacy/codes/iso3166/.'
                      type:
                        - 'null'
                        - string
                      enum:
                        - null
                        - A1
                        - A2
                        - O1
                        - AD
                        - AE
                        - AF
                        ...
                        - ZA
                        - ZM
                        - ZW
                      example: AU

Known limitations

  • Only Squiz Datastore OpenAPI v3.0 specs are supported.

  • Multiple hosts are not supported.

  • Authentication for JWT access to Squiz Datastore admin requests is supported provided the spec has the correct securitySchemas.