Datastore component

Overview

The Datastore component allows Connect to work with Squiz Datastore.

Datastore is a Squiz 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.

Triggers

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

Actions

This component provides a single action, which is any valid request to your Datastore service’s blueprint configured as this component’s credential.

While configuring your Datastore component, you can test the action by clicking the Retrieve sample from Squiz Datastore button when testing your Datastore component for your flow.

Prerequisites

Before you can start using the Datastore component with Connect, a number of conditions must be met first.

These require you to install and make use of the Experience Cloud and Datastore CLI tools.

Add and/or update your Datastore blueprint’s service

After finalising your blueprint’s OpenAPI 3.0-compliant specification and JSON schema files, add and upload the blueprint to your Datastore instance to create your Datastore blueprint’s service.

If you made any modifications to your blueprint locally and/or changed its name, ensure your blueprint is updated and/or renamed in your Datastore instance accordingly, to ensure your Datastore service is up to date.

All configured Datastore services appear on your Datastore dashboard in your Experience Cloud console.

Bundle your Datastore blueprint for Connect

To prepare your blueprint for use in Connect, you need to 'bundle' your Datastore blueprint’s API spec and data model files into a single API spec file, which can then be uploaded through Connect.

To bundle your blueprint for Connect:

  1. cd to the directory containing your blueprint’s API spec file (api.yaml) and directory of data model files (schema).

  2. Ensure you are logged in to Experience Cloud, by running the dxp login command with your Experience Cloud credentials.

  3. Run the dxp datastore bundle command to bundle your blueprint’s files into a single API spec file, for example:

    $ dxp datastore bundle --blueprint api.yaml --name "My blueprint" --output my-blueprint-bundle.yaml
    The name of your blueprint must match its name (in bold letters) on the Datastore dashboard. If the name of your blueprint contains spaces, wrap the name with double-quotes.
  4. To verify that the blueprint was successfully bundled, open the the bundled file (e.g. my-blueprint-bundle.yaml), scroll to the end of it and check its servers > url value. If this value matches the URL value of your Datastore service listed on the Datastore dashboard, then you are ready to proceed to add your bundled blueprint as a 'credential' in the Datastore component in Connect.

Configure your Datastore component

This procedure assumes that you have already set up a flow and are ready to add the Datastore component to the relevant step. Learn more about creating flows in Building a basic integration flow.

Configure the component’s blueprint credential

  1. Ensure you have accessed your flow by clicking Flows (in the nav), then the name of your flow on the main page.

  2. Click Add a new action, and in the resulting step configuration panel (Setup this step Configuration), search for 'Datastore' and choose the Squiz Datastore component from the list of options.

  3. Click Choose Squiz Datastore to confirm.

  4. In the step configuration panel (Squiz Datastore Configuration), ensure the Credentials tab is selected and click Add New Credential.

  5. In the Name Your Credential field, update the default name of your Datastore component’s credential to represent the blueprint you bundled above - e.g. 'My blueprint credential' or 'Online form credential'.

  6. Open your bundled blueprint file in a text editor.

  7. Back in Connect, copy the contents of this field into the Datastore OpenAPI .yml spec field.

  8. Access your Datastore dashboard through the Experience Cloud console, locate your added blueprint on this page and copy its Secret key value.

  9. Back in Connect, copy the contents of this secret key value into the Datastore Instance Secret Key field.

  10. For the JWT payload field, specify the payload (in JSON format) for the JSON web token that complies with the
    x-datastore-acl values defined in the blueprint for the endpoints you wish to call. To specify the payload:

    1. Examine the relevant endpoints' x-datastore-acl values in the bundled blueprint file.

    2. Aggregate all of these values and convert them into JSON format. For example, an x-datastore-acl value of:

      • jwt.isAdmin === true is
        {"isAdmin": true} in JSON format.

      • jwt.username !== null || jwt.isAdmin === true is
        {"isAdmin": true, "username":""} in JSON.

    3. Specify the JSON format value in the JWT payload field.

    datastore components credential
    Figure 1. Example of a completed Datastore component’s credential panel
  11. Click Verify verify that your Datastore component’s blueprint credential can access your Datastore service, and once you see Verified, your Datastore component is ready to use.

  12. Click Save and then click the name of your new credential on the Credentials tab to proceed to test and prepare the Datastore component for your flow.

Test and prepare the Datastore component for your flow

To test the Datastore component and its configured credential, after configuring your blueprint credential above, in the step configuration panel:

  1. In the Input tab:

    1. Select your endpoint and method from the Path & Operation field.

    2. Select the Split result if its an array check box if you want the body array in the Datastore response (interpreted by Connect) to be emitted into separate messages. Each message would then spawn separate containerized instances of your flow’s subsequent steps. Otherwise, leave this option clear to emit the entire array in a single message to the next step of the flow.

      Connect inserts the body of a Datastore response into a body element, which in itself could be either an array or object.

      This option only works if the body element is an array - i.e.

      {
        "responseCode": 200,
        "body": [
          {
            "message": ...
            ...
          },
          {
            "message": ...
            ...
          },
          {
            "message": ...
            ...
          }
        ],
        "headers": {
          ...
        }
      }

      which would result in three messages being emitted assuming this option were selected. Otherwise, if the body element were an object (i.e. "body": { …​ }), selecting this option would only result in a single message being emitted.

    3. Select the Don’t throw Error on Failed Calls check box if you want an error response from your Datastore service to be handled through your flow’s error handling feature in Connect. Otherwise, leave this option clear to allow the error response to be emitted to the next step of the flow.

    4. Use any additional fields to submit the required data to complete the request to your Datastore service.

  2. In the Sample tab, click the:

    • Retrieve sample from Squiz Datastore button to retrieve the response from your Datastore service based on your request sent from the formulated Input tab.

    • Add sample manually button to add your own manual response.

  3. Click Continue to complete your Datastore component step’s configuration for your flow.

© 2015- Squiz Pty Ltd