Enabling external data

Let’s get started by configuring the API and connections to the content sources.

Cloud Accessible API

This is the API that you as a customer would stand up and make available to Records365. The API is responsible for providing the metadata that will be used to enrich records beyond those already provided by the original content source.

Records365 supports APIs hosted in the Azure API Management service, for more information please refer to the following resource, https://azure.microsoft.com/en-au/services/api-management

The API Contract is defined below and requires the following:

Response payload schema

Field NameDescription
Statusindicator whether the request was successful or not
Datacontains a collection of objects as defined below in the Data element schema section
ErrorMessageprovides the details for any error encountered
Linkscontains two properties

  • Self – current url requested
  • Next – the next url to be invoked when the returned result set spans more than one page

 

Sample response payload
{
 "Status": "success",
 "Data": [
  {
   .......
 }
 ],
 "ErrorMessage": "",
 "Links":{
   "Self":"",
   "Next":""
  }
}

 

Data element schema

The Data element contains a collection of objects:

Field NameDescription
Ida unique value for each object in the Data element. This value will be matched against the incoming records metadata property declared by the Source primary key entry in the Records365 External data connection. When a match, the record will be applied to the Properties from this object.
CreatedDatethis field is used in date filtering on a GET request to retrieve all created items, see below for more on filtering.
ModifiedDatethis field is used in date filtering on a GET request to retrieve all updated items, see below for more on filtering.
Propertiesa collection of values that will be applied to records, must contain;

  • Name
  • Value
  • Type

Where the following Types are supported

  • String
  • DateTime
  • Boolean

Sample Data element payload

"Data": [
  {
   "Id": "f66d550c-3fb4-4422-aa6c-789425a5bb64",
   "CreatedDate": "2020-01-02T07:30:02.9179477Z",
   "ModifiedDate": "2020-06-26T17:58:42.1153638Z",
   "Properties": [
       {
        "Name": "ProjectName",
        "Value": "Marine Impact Program",
        "Type": "String"
       },
       {
        "Name": "HasSensitiveInfo",
        "Value": "true",
        "Type": "Boolean"
       },
       {
        "Name": "ProjectCreated",
        "Value": "2014-10-01T00:16:21:214T",
        "Type": "DateTime"
       }
    ]
  },
  {
  "Id": "d6579b77-b391-471e-b446-2b96f6b75ef3",
   "CreatedDate": "2021-05-25T04:20:38.2695088Z",
   "ModifiedDate": "2021-07-04T00:45:33.6399976Z",
   "Properties": [
       {
        "Name": "ProjectName",
        "Value": "Tree Habitat Carbon Offset",
        "Type": "String"
       },
       {
        "Name": "HasSensitiveInfo",
        "Value": "false",
        "Type": "Boolean"
       },
       {
        "Name": "ProjectCreated",
        "Value": "2018-06-04T00:16:21:214T",
        "Type": "DateTime"
       }
    ]
  }
]

Key Considerations for your API

Filtering – To limit the data for day to day processing your API needs to support an optional from parameter, for example ?from=[datetime]. When supplied this is to return only items that have a CreatedDate or ModifiedDate greater than or equal to the supplied value. When not supplied the entire dataset is to be returned.

Pagination – Records365 limits the amount of data retrieved from your API at any one time. To do so, your API must support the optional maxLimit parameter, for example ?maxLimit[value]. When the result set spans multiple pages your API is responsible for providing the next link as part of the response. See the Next option in the Links section of the response payload schema above.

Securing your API using best practices – Records365 supports certificate, subscription keys and a combination of both for authenticating to your API. More information on securing your API can be found here https://docs.microsoft.com/en-us/azure/api-management/api-management-howto-mutual-certificates-for-clients

Records365 External Data connection

Role Required To create and manage External Data connections you need to be assigned to the Application Administrator role.

Once you have provisioned your API to surface the additional metadata to Records365 you can then connect that API to Records365.

Create a new connection

  1. Click on the Settings icon in the top right hand corner of Records365.
  2. Click on Configuration in the left hand navigation pane and select External Data, this displays your current connections.

  1. Select the New button


Field NameDescription
Title Title for the connection, can be used for searching and filtering connections
Description Description for the connection, can be used for searching and filtering connections
EnabledAllows you to create a connection in preparation for record enrichment. Records are only enriched when the connection is enabled
API URL The url of your Cloud Accessible API providing the additional metadata
API Secret The secret applied to your API. When using Azure APIM this is found under the Subscription section of your API. A Secret or Certificate is required, however both can be used
Certificate Upload the certificate securing your API
Certificate Password The password for the uploaded certificate
Apply connection details to connector Select the SPO connector instance that manages the records to apply the additional metadata.
Source primary key The field name on submitted records that contains the value used for matching the Id for an object entry returned in the Data section of your API response payload. If no match is made then no additional metadata will be added to the record.

The fields available for use can be found in the connector specific section of the record details page.

  1. Complete the fields and select Save.

After saving the connection an initial sync of the data from your API will be performed by Records365. This allows the data to be cached in Records365 so that for each ingested record a live API request is not required.

 

Edit an existing connection

  1. From the Configuration\External Data page, which displays all of your current connections
  2. Click the Title field for the connection that you wish to modify
  3. Make the necessary changes and select Save. Please note, that changing the API URL of a connection is not currently supported. To use a different URL please create a new connection.

 

Sample connection