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 Name | Description |
|---|---|
| Status | indicator whether the request was successful or not |
| Data | contains a collection of objects as defined below in the Data element schema section |
| ErrorMessage | provides the details for any error encountered |
| Links | contains two properties
|
Sample response payload{ "Status": "success", "Data": [ { ....... } ], "ErrorMessage": "", "Links":{ "Self":"", "Next":"" }}
Data element schema
The Data element contains a collection of objects:
| Field Name | Description |
|---|---|
| Id | a 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. |
| CreatedDate | this field is used in date filtering on a GET request to retrieve all created items, see below for more on filtering. |
| ModifiedDate | this field is used in date filtering on a GET request to retrieve all updated items, see below for more on filtering. |
| Properties | a collection of values that will be applied to records, must contain;
Where the following Types are supported
|
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
- Click on the Settings icon
in the top right hand corner of Records365.
- Click on Configuration in the left hand navigation pane and select External Data, this displays your current connections.
- Select the New button
| Field Name | Description |
|---|---|
| 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 |
| Enabled | Allows you to create a connection in preparation for record enrichment. Records are only enriched when the connection is enabled |
| Update existing records with changes | When disabled, modifications to the API data set will not be applied to declared records. |
| 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. |
- 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
- From the Configuration\External Data page, which displays all of your current connections
- Click the Title field for the connection that you wish to modify.
- 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.
Delete a connection
- From the Configuration\External Data page, which displays all of your current connections
- Select the connections to be deleted. one or more connections can be deleted at one time.
- Click the Delete button.
Deleting a connection does not remove metadata from records that were previously enriched by the deleted connection.
Sample connection