Use Connect to automate activities from events in Matrix

This tutorial shows you how to integrate Squiz Connect with Matrix using a Webhook component, a Google Spreadsheets data receiver, and a Matrix trigger.

You configure a Connect webhook flow (to listen for Matrix events) and a Google Sheet data receiver (to send data to the spreadsheet). A Matrix trigger sends page publishing events through the Connect webhook and data receiver, which you configure to update a row with keyword-based facts about the publishing event.

Before you start

For this tutorial, you will require:

  • Administrator or integrator access to a Squiz Connect workspace.

  • Access to a Squiz Matrix server.

  • A Matrix user account type of system administrator. Your user account must be in the System management  System administrators user group.

  • Read and understand what a Connect Integration flow is.

  • A Google Spreadsheet named Matrix publication events with the following headings defined along the first spreadsheet row (the header row) of the default worksheet:

    • Date

    • Title

    • Summary

    • URL

    • Author

    • Region.

Create your Connect flow and data receiver for integration with Matrix

In this part of the tutorial, you configure a Connect webhook flow (to listen for Matrix events) and a Google Sheet data receiver (to send data to the spreadsheet).

Select the webhook component

Connect offers a webhook component that provides flexibility in how you integrate with many third-party systems. Create a webhook component as part of a new flow.

  1. Click the Add new flow button on the Dashboard or the Flows page.

  2. Edit the name of the flow and set it to “Matrix publishing events”.

  3. On the Flow designer page, click Add the initial trigger.

  4. Use the search bar to find the Webhook component.

  5. Click the component to select it, and then click Choose Webhook.

Set up webhook credentials

The next thing you need to do is set up “No auth” credentials for the webhook you want to use.

If you have entered credentials already on the Credentials page, they will be available for selection in a searchable list.
  1. Click Add New Credential.

  2. Enter a name for your credential. For example, “Matrix GSheet No Auth”.

  3. In the Type field, select No Auth to proceed without authentication.

  4. Click Save to select the credential and proceed to the sample data tab.

Define sample webhook data

In the Sample tab, you need to define the JSON data structure that the webhook expects to receive from Matrix.

  1. Click Add sample manually.

  2. Paste the following JSON data structure containing Matrix keywords:

    {
        "Date":"%asset_updated%",
        "Title":"%asset_name%",
        "Summary":"%asset_attribute_summary%",
        "URL":"%asset_url%",
        "Author":"%asset_updated_by_name%",
        "Region":"%asset_metadata_client.news.region%"
    }
  3. Click Save to save the valid JSON object.

  4. Click Continue to finish configuring the webhook component and load the step summary page.

  5. Make any final adjustments to the name or description, and then click Finish step to return to the Flow Designer.

Select the data receiver

After you have a trigger configured to bring data into the flow, you need to configure the next step of the flow that sends data to a Google Spreadsheets receiver.

  1. Click Add a new action.

  2. Use the search bar to find the Google Spreadsheets component.

  3. Click the action to select it, and then click Choose Google Spreadsheets.

  4. On the Versions step, select Add Spreadsheet Row.

  5. On the Functions step, click Add New Credential.

  6. On the Credentials screen, give a name to the credential.

  7. Click Authenticate to authenticate through the Google Account that provides access to the spreadsheet.

  8. Click Save to select the newly added credential as the one to use to authenticate.

  9. On the Input screen, configure the following values:

    Spreadsheet

    Select the Matrix publication events spreadsheet from the list.

    Worksheet

    Select the Sheet1 worksheet, which is the default name of the worksheet.

    Input mode

    Select the First Row As Headers option from the list.

  10. Click Continue to save the spreadsheet configuration.

  11. On the Sample screen, click Retrieve sample from Google Spreadsheets to populate the sample JSON object you set up in the Webhook configuration.

  12. Make any final adjustments to the name or description, and then click Finish step to return to the Flow Designer page.

  13. Click Publish Draft to make the integration available.

  14. Click Start Flow to make the flow watch for requests.

Take note of the Webhook URL. You will need the URL when configuring the Matrix trigger.

Configure your Matrix trigger for Connect

In this part of the tutorial, you set up a Matrix trigger that uses the webhook configuration you set up in the Connect section to send page publishing events to the Google Sheet, based on asset workflow statuses.

  1. Ensure you are logged in to your Matrix site in admin mode as a user with the system administrator account type (according to the Before you start section above).

  2. Add a new trigger asset through System management  Trigger manager.

  3. On the Create a new trigger dialog box, specify a Name and Description for the trigger:

    Name

    Track published assets in a spreadsheet.

    Description

    When a page goes live, send an event to Connect.

  4. Click Create, and then click Edit to load the Details screen of the trigger.

  5. In the Events section, select the Before status changed checkbox.

  6. In the Conditions section, add the following conditions and click Save:

    • Asset status being changed to

    • Asset is of type

    • Tree location.

  7. Choose the following values for these conditions:

    Asset status being changed to

    Select Live.

    Asset is of type > Match any one of these types

    Choose Page and select the Inherit checkbox.

    Tree location

    Select the site or part of the site where you want pages going live to trigger the notification.

  8. In the Actions section, choose Call REST resource and click Save.

  9. In the Call REST resource section, set the following field values:

    METHOD

    Choose POST.

    URL(S)

    Add the Webhook URL from the Connect Flow Designer page.

    REQUEST HEADERS

    Add Content-type: application/json to specify the content type of the request body.

    REQUEST BODY

    Copy and paste the following JSON code snippet into this text field:

    {
        "Date":"%asset_updated%",
        "Title":"%asset_name%",
        "Summary":"%asset_attribute_summary%",
        "URL":"%asset_url%",
        "Author":"%asset_updated_by_name%",
        "Region":"%asset_metadata_client.news.region%"
    }
    This JSON code snippet makes extensive use of Matrix keyword replacements. Read the Keyword replacements and modifiers documentation for more information about configuring other element values of this request body.
  10. Click the RUN TEST option to test that the trigger functions correctly after you save the trigger.

  11. Change the status of the trigger to Enabled, which makes the trigger live.

  12. Click Save to save changes to the trigger.

Confirm that the Connect flow is correctly configured with Matrix

Confirm that your Connect webhook flow and data receiver are configured correctly and that they generate the expected keyword replacement values in your Google Spreadsheet.

  1. Ensure you are logged in to your Matrix site in admin mode as a user with admin access to your site’s asset tree specified in the Tree location field.

    You configured the Tree location field as part of the Configure your Matrix trigger for Connect step.
  2. Follow the instructions in Adding assets to create a standard page asset within this asset tree.

  3. Access the new page asset’s Details screen (if not already visible), and if necessary, click Edit.

  4. Select Approve and make live from the Change status field and select the Cascade status change check box.

  5. Click Save to save the status change update to the page and observe the row added to your Google Spreadsheet.

  6. Confirm that this row contains the correct %asset_name% and %asset_url% keyword replacement values, along with the other keyword replacement values you configured.

© 2015- Squiz Pty Ltd