Available joins API - use cases and sample requests

For an overview of Available joins:

User-defined entities with joins, created via API, for use in Lists app | Available Joins

Use cases for Available joins:

1. Available joins API - use cases and sample requests | Use case 1: all sources

2. Available joins API - use cases and sample requests | Use case 2: sources to join to

3. Available joins API - use cases and sample requests | Use case 3: join combinations

Postman collection with sample requests

The linked Postman collections contains example requests to the available joins endpoint for the Eureka snapshot environment. These can be used to test this endpoint on Eureka snapshot.

• Postman collection

• Environment: https://folio-etesting-snapshot-diku.ci.folio.org/

• Note: in order to use this collection, you’ll need to get a valid token and include it in the header for the x-okapi-token

Open

Postman collection with the Available joins endpoint, including sample requests

Use case 1: all sources

I want to combine data from multiple records. I need a list of all available record types, including those not visible in the Lists app

Steps:

• POST to /entity-types/custom/available-joins

  • to get all ETs that can be used as sources, the request body is empty {}

  • {}

• Response: 200 OK, returns a list of ETs the user has access to; these ETs can be sources for joins

  • Each ET that can be used as a source is returned as an availableTargetId

  • returns simple ETs; composite ETs are not returned as potential sources (note: the sample response below was truncated)

  • { "availableTargetIds": [ { "label": "Acquisition method", "value": "37288235-e59c-4db7-a3cc-eb31effd7828", "description": "Simple entity type for acquisition method data." }, { "label": "Address types", "value": "9176c676-0485-4f6c-b1fc-585355bac679", "description": "Simple entity type for user address type data." }, { "label": "Call number type", "value": "d9338ced-3e71-4f24-b605-7912d590f005", "description": "Simple entity type for call number type data." }, { "label": "Categories", "value": "a4ab7592-fb09-4feb-8e88-b91b456ff251", "description": "Simple entity type for organization category data." }, { "label": "Composite voucher line totals per account", "value": "0013c960-d08b-4266-b7d3-5b1bea68e2dc", "description": "Composite entity type where each record represents the total amount spent per external account number within a ledger, based on voucher lines linked to vouchers and invoices. Includes related ledger and fund data when present." }, { "label": "Config data", "value": "abb28bac-e090-48c1-a48b-3fe805638041", "description": "Simple entity type for configuration data." }, { "label": "Contributor name type", "value": "6cd60e0e-f862-413a-9857-1d1ef1ca34ea", "description": "Simple entity type for contributor name type data." }, { "label": "Contributor type", "value": "a09e4959-3a6f-4fc6-a8a8-16bb9d30dba2", "description": "Simple entity type for contributor type data." }, { "label": "Department", "value": "f067beda-cbeb-4423-9a0d-3b59fb329ce2", "description": "Simple entity type for user department data." }, { "label": "Exchange rates", "value": "770a383e-c6cb-412b-abc3-6fa3c8a8795c", "description": "Simple entity type for currency exchange rates data." }, { "label": "Expense class", "value": "6e11cd39-a34e-4afc-90db-957dd45d139e", "description": "Simple entity type for finance expense class data." }, { "label": "Fee/fine accounts", "value": "fccb5cd8-c146-5c0a-8156-837f1bd3f1cc", "description": "Simple entity type for fee/fine account data." }, { "label": "Fee/fine actions", "value": "26726f53-af12-5d7d-88a8-62f13e88834d", "description": "Simple entity type for fee/fine action data." }, { "label": "Fee/fine comment requirements", "value": "b079dfb1-4d40-5fca-9da5-bc9419265d28", "description": "Simple entity type for fee/fine comment requirements data." }, { "label": "Fee/fine lost item policy", "value": "8e8b251d-4220-54c0-8396-76cd6cd83a95", "description": "Simple entity type for fee/fine lost item policy data." }, { "label": "Fee/fine manual block templates", "value": "cd21b75f-0e16-5ae2-98b4-7937b26e4e7b", "description": "Simple entity type for fee/fine manual block template data." }, { "label": "Fee/fine manual blocks", "value": "78360363-7305-5196-a685-19d1debac5a8", "description": "Simple entity type for fee/fine manual block data." }, { "label": "Fee/fine overdue fine policies", "value": "1b84ae2f-75f3-5533-9300-c740fb4a86f6", "description": "Simple entity type for fee/fine overdue fine policy data." }, { "label": "Fee/fine owners", "value": "a49dc8b4-8316-534d-94af-c5ca7748d6e9", "description": "Simple entity type for fee/fine owner data." }, { "label": "Fee/fine payments", "value": "4dc21517-cc59-5267-bd82-ac895d0e3478", "description": "Simple entity type for fee/fine payment data." }, { "label": "Fee/fine refunds", "value": "1743cbb4-922b-5042-bb9e-62a82758f00f", "description": "Simple entity type for fee/fine refund data." }, { "label": "Fee/fine transfers", "value": "6f6e4d04-d018-5e56-a4c1-260b19e5cd3f", "description": "Simple entity type for fee/fine transfer data." }, { "label": "Fee/fine types", "value": "b721ddae-0e0e-52f9-83cb-aa5cf83008fe", "description": "Simple entity type for fee/fine data." }, { "label": "Fee/fine waives", "value": "202fcf7f-ac7f-5ead-b73f-6513a47430e9", "description": "Simple entity type for fee/fine waive data." }, { "label": "Finance group", "value": "a01d982c-2c59-408e-8771-7ce0a07bc1a3", "description": "Simple entity type for finance group data." }, { "label": "Fiscal year", "value": "e61f988a-1d47-4b16-b8be-220a1c38ca8a", "description": "Simple entity type for fiscal year data." }, { "label": "Fund", "value": "4c63c7f5-1a28-4394-b401-98c02c31492d", "description": "Simple entity type for fund data." }, { "label": "Fund type", "value": "b7e43005-3e3a-4633-82b9-a96fcd7d8c47", "description": "Simple entity type for fund type data." }, { "label": "Group", "value": "e7717b38-4ff3-4fb9-ae09-b3d0c8400710", "description": "Simple entity type for user group data." }, { "label": "Holdings", "value": "30a5cfad-1868-4f46-86b9-a6ef67e2d9bf", "description": "Simple entity type for holdings record data." }, { "label": "Holdings type", "value": "b9eaaed8-c11b-4d53-a784-a4213c584001", "description": "Simple entity type for holdings type data." }, { "label": "Instance date type", "value": "2d4bd468-720e-42b2-af41-8f4a9d7cb335", "description": "Simple entity type for instance date type data." }, { "label": "Instance status name", "value": "9c239bfd-198f-4013-bbc4-4551c0cbdeaa", "description": "Simple entity type for instance status data." }, { "label": "Instance type", "value": "af44e2e0-12e0-4eec-b80d-49feb33a866c", "description": "Simple entity type for instance type data." }, { "label": "Instances", "value": "8fc4a9d2-7ccf-4233-afb8-796911839862", "description": "Simple entity type for instance data." } ], "availableJoinConditions": null }

• Data returned for each source:

  • availabletargetIds object that contains

    • label - name of the ET (not required to be unique)

    • value - UUID of the ET

    • description - basic summary of the ET being returned

Use case 2: sources to join to

The Lists app has a record type that has most of the data I need. I’d like to include some additional data from another record type

Steps:

• POST to /entity-types/custom/available-joins

  • Get a list of ETs that can be joined with a specific ET

  • the request body includes a sources object with UUID of initial source

  • { "sources": [ { "type": "entity-type", "alias": "simple_instance", "name": "Instance", "targetId": "8fc4a9d2-7ccf-4233-afb8-796911839862", //simple instances "essentialOnly": true } ] }

    • type - always "entity-type" when creating custom ETs

    • alias - place to provide a more descriptive name for the source

    • name - user facing name of the source

    • targetId - UUID of the source

    • essentialOnly -- determines if all fields from the ET should be provided, or just essential ones

• Response: 200 OK, returns a list of ETs the user has access to; these ETs can be sources for joins

  • Each simple ET that can be used as a source is returned as an availableTargetId

  • Note: composite ETs are not returned as potential sources from the available-joins endpoint

  • { "availableTargetIds": [ { "label": "Holdings", "value": "30a5cfad-1868-4f46-86b9-a6ef67e2d9bf", "description": "Simple entity type for holdings record data." }, { "label": "Instance date type", "value": "2d4bd468-720e-42b2-af41-8f4a9d7cb335", "description": "Simple entity type for instance date type data." }, { "label": "Instance status name", "value": "9c239bfd-198f-4013-bbc4-4551c0cbdeaa", "description": "Simple entity type for instance status data." }, { "label": "Instance type", "value": "af44e2e0-12e0-4eec-b80d-49feb33a866c", "description": "Simple entity type for instance type data." }, { "label": "Purchase order lines", "value": "58148257-bfb0-4687-8c42-d2833d772f3e", "description": "Simple entity type for purchase order line data." }, { "label": "Simple FOLIO Users", "value": "f2615ea6-450b-425d-804d-6a495afd9308", "description": "Simple entity type for user data. Includes only basic user information. Used for joins in composite ETs that don't require full user details." }, { "label": "Simple SRS record", "value": "d5449a05-fd57-45e5-9383-ea615246f6f9", "description": "Simple entity type for SRS records with MARC content." }, { "label": "Simple Users", "value": "bb058933-cd06-4539-bd3a-6f248ff98ee2", "description": "Simple entity type for user data." }, { "label": "Titles", "value": "cd9e34da-a81e-57e5-8111-6bab5d4ceba6", "description": "Simple entity type for acquisition title data." } ], "availableJoinConditions": null }

• Data returned for each source:

  • availabletargetIds object that contains

    • label - name of the ET (not required to be unique)

    • value - UUID of the ET

    • description - basic summary of the ET being returned

Use case 3: join combinations

I know the records or data that I want to join, but I need to identify the where/how the data can connect.

Steps:

• POST to /entity-types/custom/available-joins

  • Get a list of combinations that contain fields that can be joined with a specific ET. This request helps identify the relevant fields to populate additional sources

  • the request body includes:

    • a sources object with UUID of initial source

    • a targetId with the UUID of the ET being joined to as an additional source

      • UUIDs for possible targetIds can be found in Use case 2 above, in the response of availableTargetIds

  • { "sources": [ { "type": "entity-type", "alias": "simple_instance", "name": "Instance", "targetId": "8fc4a9d2-7ccf-4233-afb8-796911839862", //simple instances "essentialOnly": true } ], "targetId": "30a5cfad-1868-4f46-86b9-a6ef67e2d9bf" //simple holdings }

• Response: 200 OK, returns a list of join combinations from ETs the user has access to; each combination provides source and target fields that help complete source definitions

  • Relevant fields from each ET that can be joined as a source are returned in availableJoinConditions

  • A list combinations: what field(s) can be joined to the source ET

  • { "availableTargetIds": null, "availableJoinConditions": [ { "sourceField": { "label": "Instance — Instance UUID", "value": "simple_instance.id" }, "targetField": { "label": "Instance UUID", "value": "instance_id" } } ] }

• Data returned for each combination:

  • Combination(s) are returned as an object in availableJoinConditions

    • sourceField - contains relevant source details

      • label - user friendly name of the source field for the join

      • value - the field name that needs to be added into the source object

    • targetField - contains relevant target details

      • label - user friendly name of the target field for the join

      • value - the field name that needs to be added into the target object

• Once you have the relevant fields, you can use data from the response to populate a complete new source for your custom ET. Based on this example, here’s what two complete sources would look like:

  • { "sources": [ { "type": "entity-type", "alias": "simple_instance", "name": "Instance", "targetId": "8fc4a9d2-7ccf-4233-afb8-796911839862", //simple instances "essentialOnly": true }, { "type": "entity-type", "alias": "simple_holdings", "name": "Holdings", "targetId": "30a5cfad-1868-4f46-86b9-a6ef67e2d9bf", //simple holdings "sourceField": "simple_instance.id", "targetField": "instance_id", "essentialOnly": true } ] }

  • note that the first source (the base source) doesn’t have a sourceField or targetField; all other sources require the target and source to be complete