Custom URL Picker API
Read this page in wide view mode from here
From any Witboost template (Creation/Edit/Reverse/Access Control), add an Entity Search Picker with a Remote Provider:
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
... # metadata fields
spec:
... # other spec fields
parameters:
- title: My template step
properties:
... # other properties
businessConcept:
title: Business Concept
ui:field: EntitySearchPicker
ui:options:
multiSelection: true
entities:
- type: Remote
displayName: Business Concepts
fieldsToSave:
- id
- value
- description
- referenceGlossary
columns:
- name: 'Name'
path: '{{value}}'
- name: 'Description'
path: '{{description}}'
- name: 'Glossary'
path: '{{referenceGlossary}}'
displayField: '{{value}}'
userFilters: ['search']
apiSpec:
retrieval:
baseUrl: 'https://my-witboost-instance/api/proxy/picker'
path: '/v1/resources'
method: 'POST'
params:
sparql: 'business-concept-query'
steps:
... # steps
In the above example, we are adding an Entity Search Picker field called businessConcept to a template. The options of the drop-down list of the Entity Search Picker will be retrieved by calling the POST /v1/resources endpoint of this API, with the given parameters.
The service source code can be found in the Witboost Starter Kit
If you want to supply API keys or any other sensitive information in the API calls, you can reference a configuration key from your Witboost values.yaml, this way:
# your Witboost values.yaml
ui:
appConfig:
mesh:
builder:
scaffolder:
microserviceConfiguration:
- microserviceId: your-microservice-id
baseUrl: https://my-witboost-instance/api/proxy/picker
retrievalPath: /v1/resources
validationPath: /v1/resources/validate
retrievalMethod: POST
validationMethod: POST
apiKey: ${SERVICE_API_KEY}
And then in your template:
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
... # metadata fields
spec:
... # other spec fields
parameters:
- title: My template step
properties:
... # other properties
businessConcept:
title: Business Concept
ui:field: EntitySearchPicker
ui:options:
multiSelection: true
entities:
- type: Remote
displayName: Business Concepts
fieldsToSave:
- id
- value
- description
- referenceGlossary
columns:
- name: 'Name'
path: '{{value}}'
- name: 'Description'
path: '{{description}}'
- name: 'Glossary'
path: '{{referenceGlossary}}'
displayField: '{{value}}'
userFilters: ['search']
apiSpec:
retrieval:
microserviceId: your-microservice-id
params:
sparql: 'business-concept-query'
steps:
... # steps
The Custom URL Picker service is meant to be called by the Witboost UI from the users' browsers. Therefore, the base URL of the API should be the one of your Witboost instance e.g. https://business-terms-picker.my-company-domain.
If you prefer to not expose the API from a dedicated URL, you can also configure the Custom URL Picker to be called through the Witboost proxy, by adding the following configuration to your values.yaml:
# your Witboost values.yaml
ui:
appConfig:
proxy:
endpoints:
/picker:
credentials: dangerously-allow-unauthenticated
target: http://{service-name}.{namespace}:{port}
allowedHeaders: ['Authorization', 'referer', 'origin']
But in this case, you must handle authentication on the service side, e.g. by validating the API key sent by Witboost.
Retrieve drop-down list options
Called by the Custom URL Picker to get the options to show to the user in the drop-down list on the UI.
The user can filter out results by typing in the Custom URL Picker field. The microservice will return the first limit elements that match the filter, skipping the first offset elements.
query Parameters
| filter | string Example: filter=banana The user input, that is typed by the user on the UI field, which is used to filter the values on the glossary. If not provided, the microservice will return all the values in the glossary following the pagination settings. |
| offset required | number Example: offset=0 the number of values to skip for each request |
| limit required | number >= 5 Example: limit=5 the number of values to return at each request |
Request Body schema: application/jsonoptional
A free-form object that can be used to define additional properties to use while performing a search in the glossary. This can be filled with other fields values coming from the template.
Responses
Request samples
- Payload
{- "kind": "fruit"
}Response samples
- 200
- 400
- 500
[- {
- "id": "banana",
- "value": "Banana",
- "description": "A yellow fruit"
}, - {
- "id": "apple",
- "value": "Apple",
- "description": "A fruit"
}
]Validate a selected option against the glossary
Called by the Custom URL picker to validate the selected values against the ones included in the glossary e.g. for checking if the selected values are still present in the glossary.
This API gets called when the user wants to modify some values e.g. by using the Edit Template, and a check is being run to see if the previously selected value is still present in the glossary with the exact shape.
Request Body schema: application/json
required | Array of objects (SelectedObject) the selected options to validate |
| queryParameters | object This field represents additional parameters to put in the request body. The user can use it to define additional properties to use while performing a validation on the "selectedObject". |
Responses
Request samples
- Payload
{- "selectedObjects": [
- {
- "id": "banana"
}
], - "queryParameters": {
- "kind": "fruit"
}
}Response samples
- 200
- 400
- 500
"Validation succeded"