Datastore
Choose the right component
Use the flowchart below to assist in choosing the appropriate component for your use case:
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 Integrations, several conditions must first be met:
- Install the DXP CLI tools
-
Read the DXP CLI documentation for further instructions.
- Add or update your Datastore blueprint’s service
-
Read the DXP CLI Blueprint commands documentation for further instructions.
- Prepare (bundle) your Datastore blueprint for Integrations
-
Read the DXP CLI Bundle commands documentation documentation for further instructions.
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 Integrations 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/5xxrange. If this option is selected, the error response will be emitted to the next flow step. - Split result if its an array
-
If selected, Integrations 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