Advanced Operations

Introduction

The following summarizes a series of advanced operations that can be performed via the Administrative API. To perform these actions, a token is needed from a user who has been assigned a role that includes the API administration permission (API_ADMIN). For more details on any endpoint, see Swagger

Operations for creating or modifying objects

Getting the body of objects

The following endpoints allow the creation or modification of object metadata in Anjana.

All the bodies needed for creating/editing objects can be obtained by calling the endpoint

GET https://{{host}}/gateway/api/admin/kerno/body-create-update/{objectSubType}/{idObject}

This call will return the body of the object corresponding to the idObject, which can be used for modifications to it. To get the body needed to create a new object, the idObject should not be sent.

For more information about what should be included as a value depending on the metadata field type, see the User Guide for examples.

Information about how ARIs are composed for fields that use ARIs (those related to files or entities) can be found in the ARIs document.

Creating and editing native entities

These endpoints allow creating and editing native entities (DATASET, DSA, INSTANCE, SOLUTION, and PROCESS) along with everything they involve (internal relationships, extra entities in the case of the dataset, etc.).

Unlike the standard API, here each entity type has its own endpoint and the operation ends directly in the status included in the request. The request body is obtained as described in the previous section.

In all cases, just as from the portal, the submitted data is validated and the operation is only completed if all validations are passed; otherwise, the errors will be reported.

Creating native entities

Step 1. Prepare the request body.

Get the body as described in the previous section. Under no circumstances is it allowed to modify the PKs or primary keys.

Step 2. Call the endpoint corresponding to the entity type.

Editing native entities

Step 3. Prepare the request body and provide the idObject.
Get the body as described in the API Basic Interactions section and provide the idObject variable in the URL.

Step 4. Call the corresponding editing endpoint.

Handling of sub-entity lists (dataset-fields, contained entities, instances, dataset input/output):

• Send the list as null → that relationship is not edited.

• Send an empty list → interpreted as delete / leave without elements (in a dataset, this deletes all dataset-fields).

Editing behavior

• Versioning: if the configuration indicates that changes version the object, a new version is generated with the changes and the entity that was sent for editing is deprecated.

• Non-editable fields: they can be edited by sending the disableNonEditValidations parameter (disabled by default).

• Tot invocation: for a governed dataset with APPROVED status and for a DSA with APPROVED status (sending the information about the edit performed).

Generic creation and update of entities

In addition to the type-specific endpoints, there is a generic endpoint that allows creating or editing any entity (native or non-native), ending directly in the status you want, without needing a workflow (for example, creating an entity already in APPROVED status, or editing from APPROVED to DRAFT).

This endpoint applies controls similar to creation from the portal: it does not allow creating duplicate objects or including incorrect values in the fields.

For DATASET, SOLUTION, INSTANCE, or DSA entities, it is recommended to use the type-specific APIs, which provide more information about complete native entities.

Creating an entity

Step 1. Prepare the request body.
The idObject must always be null since this is a creation. All the subtype's attributes are included within the entityAttributes property; the remaining properties depend on the subtype you want to create (see table below).

Step 2. Call the generic endpoint.

POST https://{{host}}/gateway/api/admin/kerno/create-update/entity/{objectSubType}

Subtype-specific properties:

Updating an entity

Step 3. Prepare the request body and provide the idObject.
The same endpoint is used as in creation, but indicating the idObject both in the URL and in the body.

Step 4. Call the generic editing endpoint.

POST https://{{host}}/gateway/api/admin/kerno/create-update/entity/{objectSubType}/{idObject}

Restriction: an entity in PENDING status that already has a workflow in progress cannot be edited; the workflow must be finished before editing it.

Editing considerations:

• Non-editable fields: they can be edited by sending the disableNonEditValidations parameter (disabled by default).

• Complete native entities: it may be necessary to create the internal relationships, or to use only the internal relationships if you only want to edit the internally related objects. See the Editing native entities section.

• Attribute language: the language must be included for international attributes. For boolean, user, list-of-values, etc. attributes, no language is included and the value must be indicated as defined in attribute_definition_value.

Deleting an entity

Allows deleting an entity. It consists of the following call:

DELETE https://{{host}}/gateway/api/admin/kerno/delete/entity/{idObject}.

This endpoint deletes all the entity's information and any related information that applies:

• Deletion of relationships associated with the entity (with their attributes)

• Deletion of workflow information associated with the entity (both in kerno and the workflow in activiti, which will be deleted, along with all its notifications)

• Deletion of any existing combinations if the deleted object is a DATASET or DSA

• Deletion of information saved in the cart related to the entity being deleted

• Deletion of the entity itself (with its attributes)

• Deletion of the entity's indexed information (including snapshots)

• Deletion of the indexed information of the relationships with the entity (including snapshots)

Processes or solutions that would leave orphaned instances cannot be deleted.

Entities that have any type of associated relationship cannot be deleted; a notice will be sent to the owners of the objects at both ends of the relationship informing them that the relationships must be deleted first in order to delete their related objects.

Creating and updating non-native relationships

This endpoint allows creating or editing a non-native relationship, ending directly in the status you want, without needing a workflow (for example, creating it from scratch directly in APPROVED, or editing from APPROVED to DRAFT).

It applies controls similar to creation from the portal: it does not allow creating duplicate objects or including incorrect values in the fields.

Creating a relationship

Step 1. Prepare the request body.
The idObject must always be null since this is a creation. All the relationship's attributes are included within the relationshipAttributes property. The source and destination attributes are mandatory.

Step 2. Call the endpoint.

POST https://{{host}}/gateway/api/admin/kerno/create-update/relationships/{objectSubType}

Updating a relationship

Step 3. Prepare the request body and provide the idObject.
The same endpoint is used as in creation, but indicating the idObject both in the URL and in the body.

Step 4. Call the editing endpoint.

POST https://{{host}}/gateway/api/admin/kerno/create-update/relationships/{objectSubType}/{idObject}

Restriction: an entity in PENDING status that already has a workflow in progress cannot be edited; the workflow must be finished before editing it.

Editing considerations:

• Non-editable fields: they can be edited by sending the disableNonEditValidations parameter in the body (disabled by default).

• Attribute language: the language must be included for international attributes. For boolean, user, list-of-values, etc. attributes, no language is included and the value must be indicated as defined in attribute_definition_value.

Deleting a relationship

Allows deleting a relationship. It consists of the following call:

DELETE https://{{host}}/gateway/api/admin/kerno/delete/relationship/{idObject}

This endpoint deletes all the relationship's information and any related information that applies:

• Deletion of workflow information associated with the relationship (both in kerno and the workflow in Activiti, which will be deleted, along with all its notifications)

• Deletion of the relationship itself (with its attributes)

• Deletion of the relationship's indexed information (including snapshots)

Other operations

Getting the metadata of an entity

This endpoint allows obtaining the data of a defined metadata for an entity; that data is returned in the same way it is received in the portal, that is, with the structure of menus and sections (including the dummy menu and sections for custom fields).

It consists of the call:

GET https://{{host}}/gateway/api/admin/kerno/entity/{objectSubType}/{idObject}

Changing the Organizational Unit of an entity

Allows you to change an entity's organizational unit without going through the workflow validation that normally applies.

It consists of the call

POST https://{{host}}/gateway/api/admin/kerno/change-organizational-unit/{{idObject}}

The validations applied are the same as from the portal; you cannot change the OU of an entity that does not exist, or of those that do not have their own OU, such as INSTANCE.

Changing the status of an entity

Allows changing an entity's status to any status, without applying the logic that status usually has (e.g.: changing it to expired would only change the entity, not its relationships, and would not involve Tot if necessary, etc.).

It consists of the call:

PUT https://{{host}}/gateway/api/admin/kerno/entity/change-state/{idObject}/{state}

If the DATASET status is changed, its DATASET FIELD entries will be updated with the same status.

Changing the status of a relationship

Allows changing a relationship's status to any status allowed for relationships, without applying the logic involved in updating an entire relationship. Changing the status of a native relationship is not allowed.

It consists of the call:

PUT https://{{host}}/gateway/api/admin/kerno/relationship/change-state/{idObject}/{state}

where idObject is the id of the relationship to modify and state is the status to change to.

Changing the name of an entity or relationship

Performs a name change on the entity or relationship specified in the request body.

Before changing the name, the PK validations corresponding to the subtype of the entity or relationship being modified will be applied. Therefore, if a name is entered that already exists for another (or the same) entity, the user will receive an exception in the response to the request.

The renaming will affect all persisted instances of the object's name and the object's ARI.

• Database

  • entity or relationship

  • audit

  • notifications

  • workflows

• Indexing

Points to note:

• The name cannot exceed 255 characters.

• Renaming objects that have a workflow in progress is not allowed.

• For changing the name of an approved DSA that contains governed entities, it is advisable to review the corresponding plugin's documentation.

• Overwriting the name of objects in PENDING status is not allowed, nor for objects that have another version.

Getting attributes that depend on other attributes

Indicates, for the value of a given attribute, which attribute values depend on the one specified. It can be applied to all subtypes or to the relationship that applies to just one.

It consists of the call:

POST https://{{host}}/gateway/api/admin/kerno/relationship

Description of the variables, all of which are mandatory:

• nameAttributeSource Name of the source attribute

• nameAttributeDest Name of the destination attribute

• valueAttributeSource List of source values for which we want to know their related values

• objectSubType Subtype of the template in which the attributes are defined

Bulk editing of objects

Allows editing the same attributes with the same values for a list of objects.

It consists of the call:

PUT https://{host}/gateway/api/admin/kerno/attribute/update/{objectType}/{objectSubType}

Optionally, another parameter is included in the call: validateType. This parameter indicates whether you want to validate the type of the parameters (for example, that numbers are numbers, or that the value is valid in fields with limited values); by default it is set to true and should only be included if you want to disable those validations.

As a result, you will receive an OK (200) if everything went well, or a PARTIAL CONTENT (206) if some object could not be edited, indicating the error that occurred (it will be a list with as many elements as objects that failed to be edited).

Withdrawal from a DSA

Allows executing the withdrawal from a DSA for the user indicated in the request.

It consists of the call:

POST https://{{host}}/gateway/api/admin/kerno/disadhere/{idObject}

The only users who are not allowed to be withdrawn are the owners of the DSA's organizational unit.

Indexing of all entities

Allows completely updating the SolR collection of Anjana's objects (only the kerno one, not the snapshots), removing all existing objects and reindexing.

It consists of the call:

PUT https://{{host}}/gateway/api/admin/kerno/index/all-entities

This endpoint launches the processing and indexing of all objects in the background. Depending on their size and the server configurations, the process may take a while.

Internally, it is done in configurable blocks. If the process does not correctly index all the elements, review and adjust the block configuration so that it fits what the system can support.