Integration

To enable ease of integration with internal Australian Data Archive services and external partner services, CADRE can support the automatic creation of requests without the user themselves having to search for the catalogue items themselves.

Catalogue Applications

Page Functionality

Redirect the user to https://cadre.ada.edu.au/catalogue/application when you want automatic creation of requests based on their resource identifiers. The page will find the catalogue item by it's respective resource identifier, create a new request based on the found catalogue item, and then finally navigate the user to the newly created request. The procedure for finding catalogue items, selecting catalogue items and then navigating users can all be controlled and changed using query parameters. The details for each query parameter and their values can be set to achieve the desired functionality is described in the sections below.

Parameter "id" Usage

The 'id' parameter is mandatory as it specifies which catalogue items to generate a request for. As an example, say we want to redirect users to the 'Catalogue Applications' page and automatically create a request for them for the catalogue item 'ANU Poll 2008: Environment'. We'll need the equivalent resource identifier for the catalogue item which can be found on either the https://cadre.ada.edu.au/catalogue or the https://cadre.ada.edu.au/asset-control?tabs=catalogue pages. In this case, the resource identifier for 'ANU Poll 2008: Environment' is 'doi:10.4225/87/FGSF5V' and thus the URL will be: https://cadre.ada.edu.au/catalogue/application?id=doi:10.4225/87/FGSF5V. In this link, the 'id' parameter is being set to create the request for the catalogue item using the following syntax: '?id=doi:10.4225/87/FGSF5V'.

Head's Up!

There is no limit imposed for the number of resource identifiers which the page can process.

As long as they are all valid identifiers and as long as the user has not already requested any of the identifiers, then they will all be generated.

If 'id' is omitted from the URL, then the page will raise an error as a request could not be created. When this occurs, the following messaging will appear for the users:

No Resources Were Given

On the other hand, if invalid resource identifiers are passed as query parameters to the page, the page will display an error.

Equivalent Resource Identifier Was Not Found

To check and ensure that a catalogue item with a given resource identifier exists, invoke the https://cadre.ada.edu.au/rems/api/catalogue/resource route, passing the resource identifier, e.g.:

curl -X 'GET' \
  'https://cadre.ada.edu.au/rems/api/catalogue/resource?resource=<YOUR-IDENTIFIER>' \
  -H 'accept: application/json'

If the API responds with '{"error": "not found"}' the resource either doesn't exist or has since been disabled or archived. Otherwise, the response '{"success": "true", "results": 1}' means that the resource does exist and can therefore be requested. If your service is integrated with CADRE, we recommend checking that the resource exists before redirecting them.

Parameter "redirect" Usage

The 'redirect' query parameter controls whether or not a user is redirected to the newly created request if it was successfully created. It will also only accepts either 'true' or 'false' values where 'true' will redirect users and 'false' will not redirect users.

The 'redirect' query parameter is optional and is 'true' by default meaning that if omitted, it will always redirect users to their newly created request. This means that the following URLs are functionality the same:

Note!

Furthermore, if multiple 'id' keys are provided on the request, the 'redirect' key is disregarded as it's ambigious which 'id' to redirect to.

If redirect is 'false' (e.g., https://cadre.ada.edu.au/catalogue/application?id=doi:10.4225/87/FGSF5V&redirect=false) after the application is successfully created, the user will have the option to navigate to the newly created request as shown in the example below.

No Redirect

Warning!

If (for whatever reason) multiple duplicate query parameters with the 'redirect' key are given, all duplicates must be 'true' for CADRE to redirect the user to the successfully created request.

Parameter "combine" Usage

When multiple catalogue items are present (by including multiple 'id' parameters), the 'combine' query parameter controls whether or not to package each requested catalogue item into separate requests or into a single request. It will also only accepts either 'true' or 'false' values where 'true' will attempt to create a single request whilst 'false' will create separate requests for each catalogue item. This works by grouping the catalogue items by either workflow identifier (wfid) and if catalogue items have the same wfid they will be put into the same request.

The 'combine' query parameter is optional and is 'true' by default meaning that if omitted, it will always attempt to group catalogue items by their wfid. This means that the following URLs are functionality the same:

To contast, the following will create individual requests for each of the requested catalogue items

https://cadre.ada.edu.au/catalogue/application?id=doi:10.4225/87/FGSF5V&id=doi:10.26193/BC2QEB&combine=false

Parameter "allow-pattern-match" Usage

The 'allow-pattern-match' parameter enables the best-effort functionality for finding similar catalogue items by resource-id. It will only accept either 'true' or 'false' values, where 'true' will try to match the 'id' against other similar resource identifiers and then giving the option of choice whilst 'false' only allow an exact match against the given 'id'. The 'allow-pattern-match' query parameter is optional and is 'false' by default meaning that if omitted, it will never attempt to match similar 'id' against other resource identifiers.

In the screenshot below, we have an example which uses the 'allow-pattern-match'. When an exact dataset could not be found, the user is given the option to choose between the similar datasets to then submit and create a request with.

Matching datasets by pattern but not using subset terminology

Parameter "pattern-matched-messaging" Usage

The 'pattern-matched-messaging' parameter changes the supporting text for the 'allow-pattern-match' interface to either be in regards to best effort or subset. The parameter is optional, will only accept either 'subset' or 'generic' as string values, and will be 'generic' by default. This parameter allows for flexibility depending on the intentions when implementing the 'allow-pattern-match' interface. Setting the parameter to 'subset' will change the support text to explain that the dataset has subsets which contain portions of a larger dataset. Whilst setting the parameter to 'generic' will change the supporting text to explain that a best-effort search returned the following catalogue items. In the screenshot below the query parameter is set to 'subset':

Matching datasets by pattern and using subset terminology

3. Production configuration