Manage relations between Fact Sheets and filter Fact Sheets for relation validity through the GraphQL API.
Creating Relations Between Fact Sheets
To create relations between Fact Sheets, use the updateFactSheet mutation. Apply the add patch operation with a path that identifies the relation attribute. You can create multiple relations with one request.
To get individual error messages for each relation in case of possible errors, add a suffix in the following format /new_1 to the path values. Use a unique suffix for each relation.
Example mutation:
mutation ($patches: [Patch]!) {
updateFactSheet(id: "4d121f64-116b-4ccc-a292-eb4e4f8d1b24", patches: $patches) {
factSheet {
id
name
... on Application {
relApplicationToITComponent {
edges {
node {
id
}
}
}
}
}
}
}
Variables:
{
"patches": [
{
"op": "add",
"path": "/relApplicationToITComponent/new_1",
"value": "{\"factSheetId\":\"9deb9733-5701-42f1-8c52-c165acaa6487\"}"
},
{
"op": "add",
"path": "/relApplicationToITComponent/new_2",
"value": "{\"factSheetId\":\"a8fe4825-42b8-431b-8124-ca12c579c78b\"}"
}
]
}
Example response:
{
"data": {
"updateFactSheet": {
"factSheet": {
"id": "4d121f64-116b-4ccc-a292-eb4e4f8d1b24",
"name": "AC Management Cloud",
"relApplicationToITComponent": {
"edges": [
{
"node": {
"id": "41ff8420-05d2-46e8-9912-975a9263f27e"
}
},
{
"node": {
"id": "8a039155-774b-4c09-94b1-e221eb0fee1c"
}
}
]
}
}
}
}
}
The following response contains an example error message that may be returned by the server. The path attribute identifies the corresponding patch operation from the request.
Example error response:
{
"data": {
"updateFactSheet": null
},
"errors": [
{
"message": "[FS_VALIDATION_RELATION_NOT_UNIQUE_OUTGOING] Outgoing relation occurred twice! relation name = 'applicationITComponentRelation', from = 'AC Management Cloud', from type = 'Application', to = 'App Maintenance & Support Service', to type = 'ITComponent'",
"path": [
"result"
],
"extensions": {
"entityType": "FACT_SHEET",
"objectId": "4d121f64-116b-4ccc-a292-eb4e4f8d1b24",
"objectPath": "/relApplicationToITComponent/fbec0812-ec6b-4c2c-8df2-525d5d3f3121",
"errorType": "MODEL_COMPLIANT"
}
}
]
}
Updating Relations Between Fact Sheets
To update relations between Fact Sheets, use the updateFactSheet mutation. Apply the replace patch operation with a path attribute that contains the id of the relation.
In the example, we update an existing relation by unlinking a Fact Sheet and linking a new one.
Example mutation:
mutation ($patches: [Patch]!) {
updateFactSheet(id: "4d121f64-116b-4ccc-a292-eb4e4f8d1b24", patches: $patches) {
factSheet {
id
name
... on Application {
relApplicationToITComponent {
edges {
node {
id
}
}
}
}
}
}
}
Variables:
{
"patches": [
{
"op": "replace",
"path": "/relApplicationToITComponent/41ff8420-05d2-46e8-9912-975a9263f27e",
"value": "{\"factSheetId\":\"ed46809c-998a-4fd6-9185-4b25e4e77d9b\", \"description\":\"Update related Fact Sheet\"}"
}
]
}
Example response:
{
"data": {
"updateFactSheet": {
"factSheet": {
"id": "4d121f64-116b-4ccc-a292-eb4e4f8d1b24",
"name": "AC Management Cloud",
"relApplicationToITComponent": {
"edges": [
{
"node": {
"id": "8a039155-774b-4c09-94b1-e221eb0fee1c"
}
},
{
"node": {
"id": "41ff8420-05d2-46e8-9912-975a9263f27e"
}
}
]
}
}
}
}
}
Deleting Relations Between Fact Sheets
Before you delete relations between Fact Sheets, get the id of relations. To do that, use the factSheet query and copy the id of the desired relations from the response.
Example query:
{
factSheet(id: "4d121f64-116b-4ccc-a292-eb4e4f8d1b24") {
name
type
... on Application {
relApplicationToITComponent {
edges {
node {
id
}
}
}
}
}
}
Example response:
{
"data": {
"factSheet": {
"name": "AC Management Cloud",
"type": "Application",
"relApplicationToITComponent": {
"edges": [
{
"node": {
"id": "8a039155-774b-4c09-94b1-e221eb0fee1c"
}
},
{
"node": {
"id": "41ff8420-05d2-46e8-9912-975a9263f27e"
}
}
]
}
}
}
}
Once you get the id of relations that you want to delete, use the updateFactSheet mutation. Provide the relation id in the remove patch operation. In the example, we delete two relations that we created.
Example mutation:
mutation ($patches: [Patch]!) {
updateFactSheet(id: "4d121f64-116b-4ccc-a292-eb4e4f8d1b24", patches: $patches) {
factSheet {
id
name
... on Application {
relApplicationToITComponent {
edges {
node {
id
}
}
}
}
}
}
}
Variables:
{
"patches": [
{
"op": "remove",
"path": "/relApplicationToITComponent/8a039155-774b-4c09-94b1-e221eb0fee1c"
},
{
"op": "remove",
"path": "/relApplicationToITComponent/41ff8420-05d2-46e8-9912-975a9263f27e"
}
]
}
Example response:
{
"data": {
"updateFactSheet": {
"factSheet": {
"id": "4d121f64-116b-4ccc-a292-eb4e4f8d1b24",
"name": "AC Management Cloud",
"relApplicationToITComponent": {
"edges": []
}
}
}
}
}
Setting an Empty Relation on a Fact Sheet
You can intentionally set a relation on a Fact Sheet as empty. This implies that the Fact Sheet is not related to or dependent on other Fact Sheets and this data is not missing. Setting an empty relation affects the completion score of a Fact Sheet because the relation field is treated as filled. For more information, see Leave Empty in the user documentation.
To set a relation as empty, use the updateFactSheet mutation and apply a patch operation. The naFields attribute indicates fields and relations that are intentionally left blank. In the example, we set the relToParent relation as empty, which means that the Fact Sheet is not linked to any parent Fact Sheets.
Example mutation:
mutation ($patches: [Patch]!) {
updateFactSheet(id: "4d121f64-116b-4ccc-a292-eb4e4f8d1b24", patches: $patches) {
factSheet {
id
name
naFields
}
}
}
Variables:
{
"patches": [
{
"op": "add",
"path": "/naFields",
"value": "[\"relToParent\"]"
}
]
}
Example response:
{
"data": {
"updateFactSheet": {
"factSheet": {
"id": "4d121f64-116b-4ccc-a292-eb4e4f8d1b24",
"name": "AC Management",
"naFields": [
"relToParent"
]
}
}
}
}
Filtering Fact Sheets for Relation Validity
Introduction to Relation Validity
Relation validity ("activeFrom" and "activeUntil") is the time interval during which a Relation
between Fact Sheets is deemed to exist. The two values are dates in ISO format like 2018-07-01
(no time).
Any of them may be unspecified, which means the Relation validity is not bounded in this direction of time. If both of these values of the Relation are not set, then the Relation is considered to always exist.
Filtering Relations Between Fact Sheets by Validity
For this purpose, the DateFilterInput argument type contains the fields from and to and the
DateFilterType in field type.
These are the possible values of the type field:
- Of main importance is only the date filter type
RANGE. RANGE_STARTandRANGE_ENDSare not implemented for Relation validity filtering and behave like
RANGEfor now.POINTbehaves likeRANGE, but the given value fortois ignored and always considered
to be equal tofrom.TODAY,END_OF_MONTH, andEND_OF_YEARare special cases ofPOINTwhere the given values of
fromandtoare ignored and considered to be equal to the day corresponding to the type.
The values of the fields from and to are dates in ISO format (no time) and define the filter interval. Any of the two values may
be null, meaning the interval is unbounded in that direction.
The Relation validity filtering semantics is the following:
A Relation is matched by the filter if and only if the Relation validity interval has a non-empty
intersection with the filter interval. In other words, if the time span defined by the
Relation's activeFrom and activeUntil fields
and the time span defined by the filter's from and to fields overlap.
Options for Filtering Relations
In the GraphQL API, you can filter Fact Sheets for relation validity in the:
Filtering Relations in the Relation Facet
In the GraphQL API, filtering for relation validity is available at the following spots:
You can filter relations in the relation facets (filter ->facetFilter -> dateFilter argument of the allFactSheets top level query field).
Note: For now, instead of the dateFilter on the individual relation facets, the dateFilter on the lifecycle facet is used. This will change in a future version. The key field of this lifecycle filter facet is ignored for the purpose of relation validity filtering.
Example query:
{
allFactSheets(filter:
{facetFilters: [
{facetKey:"FactSheetTypes" keys:["UserGroup"]}
{facetKey: "relUserGroupToApplication" keys: ["e3a08f5f-5c3e-4dc1-8444-ed87bdd48634"]}
{facetKey:"lifecycle" keys:"__any__" dateFilter:{type:RANGE from:"2018-07-01" to:"2018-07-31"}}
]})
{
edges {
node {
type
displayName
}
}
}
}
Filtering Relations in the Relation Validity Filter
This is a filter that restricts the Relations that are returned in the relation fields of a concrete Fact Sheet type, for example, field relApplicationToUserGroup in typeApplication. Those fields accept an argument validityFilter containing the fields activeFrom and activeUntil, which behave like from and to in DateFilterInput (see above).
Example query:
{
factSheet(id: "e3a08f5f-5c3e-4dc1-8444-ed87bdd48634") {
displayName
... on Application {
relApplicationToUserGroup(validityFilter: {activeFrom: "2018-07-01", activeUntil: "2018-07-31"}) {
edges {
node {
activeFrom
factSheet {
displayName
}
}
}
}
}
}
}