Business Specific Metadata Operations

Overview

Business Specific Metadata operations allow full control over the additional metadata that can be added to extend the core Noark5 entities. Business specific metadata can be added to the following set of core entities :

child-parent-relation

  • Class (Klasse)

  • Folders

    • Basic Folder (Mappe)
    • Meeting Folder (Moetomappe)
    • Case File (Saksmappe)
      • Case Party (Sakspart)

  • Records

    • Basic Record (Registrering)
    • Meeting Record (Moetoregistrering)
    • Registry Entry (Journalpost)
      • Correspondence Party (Korrespondansepart)

  • Document (Dokument)

Business specific metadata fields are organized in groups. Each of the BSM fields are defined as part of a group and have specific type (like string, long, etc.) and also can be defined to accept any value of the type or have a predefined lists of possible values.

Both BSM group identifier (groupID) and BSM field identifier (fieldId) are user defined values, uniqie in the Documaster Archive instance and can be shared across Archives (Fonds).

GET /noark5/v1/bsm-registry?{groupId,fieldId}

The operation is used to retreive the available business specific data groups and their fields. The returned data can be filtered based on the query parameters available, by the ID of the BSM group or the ID of the BSM field.

HTTP Request
Field Location Mandatory Type Description
Authorization string access token aquired as part of the authentication call, prefixed with Bearer
X-Documaster-Error-Response-Type string custom header indicating that any error should be reported in JSON format, rather than the standard text format, should always be provided as application/json
groupId string identifier of the BSM group which should be returned, groupId is a user defined value used to identify the group
fieldId string identifier of the BSM field which should be returned, fieldId is user defined value used to identify the field

groupId and fieldId query parameters can be used together or separately.

HTTP Response

The operation returns HTTP 200 OK in case of success or any of the standard error codes defined.

Field Location Type Description
Content-Type string content type header, always is application/json
$.results[] array list of code list values grouped by entity type
$.results[].groupId string unique BSM group identifier througout the Documaster instance
$.results[].groupName string BSM group description
$.results[].groupDescription string BSM group fields list
$.results[].fields[] array unique BSM field identifeir throughout the Documaster instance
$.results[].fields[].fieldId string BSM field name
$.results[].fields[].fieldName string BSM field description
$.results[].fields[].fieldDescription string BSM field type, possible values are : string, long, double, timestamp, and encrypted
$.results[].fields[].fieldType string
$.results[].fields[].fieldValues[] array

This operation does not support pagination and limit of the number of values returned, so use it carefully, especially when the BSM groups and fields defined may be of high number.

      Request

GET https://<documaster-instance>.local.documaster.tech:8083/rms/api/public/noark5/v1/bsm-registry?groupId=bsm-group-system-a HTTP/1.1
...
Authorization: Bearer {{accessTokenIntegrator}}
X-Documaster-Error-Response-Type: application/json

      Response

HTTP/1.1 200 OK
...
Content-Type: application/json

{
    "results": [
        {
            "groupId": "bsm-group-system-a",
            "groupName": "BSM Group for System A",
            "groupDescription": "Business Specific Metadata Group for System A",
            "fields": [
                {
                    "fieldId": "bsm-field-customer-id",
                    "fieldName": "Customer ID",
                    "fieldDescription": "BSM Field for Customer identifier in Business System A",
                    "fieldType": "long"
                },
                {
                    "fieldId": "bsm-field-gender-pronouns",
                    "fieldName": "Gender Pronouns",
                    "fieldDescription": "BSM Field for gender pronouns",
                    "fieldType": "string",
                    "fieldValues": [
                        "he/him/his",
                        "she/her/hers",
                        "they/them/theirs"
                    ]
                }
            ]
        }
    ]
}

// Noark5Client is created and access token is provided

// Requesting BSM groups filtered by groupId = bsm-group-system-a
List<BsmGroupInfo> bsmGroups = client.bsmRegistry("bsm-group-system-a", null).getGroups();

// Iterating over the returned groups and the fields defined
for (BsmGroupInfo bsmGroup : bsmGroups) {
    System.out.println(bsmGroup.getGroupName());

    for (BsmField bsmField : bsmGroup.getFields()) {
        System.out.println("    - " + bsmField.getFieldName());
    }
}

// NoarkClient is created and access token is provided

// Requesting BSM groups filtered by groupId = bsm-group-system-a
List<MetadataGroupInfo> bsmGroups = client.BsmRegistry("bsm-group-system-a", null).Groups;

// Iterating over the returned groups and the fields defined
foreach (MetadataGroupInfo bsmGroup in bsmGroups) {
    Console.WriteLine(bsmGroup.GroupName);

    foreach (MetadataFieldInfo bsmField in bsmGroup.Fields) {
        Console.WriteLine("    - " + bsmField.FieldName);
    }
}

PUT /noark5/v1/bsm-registry/group/{groupId}

The operation is used to create or update a business specific metadata group definition. The operation cannot update the BSM fields part of the group, just the group metadata.

HTTP Request
Field Location Mandatory Type Description
Authorization string access token aquired as part of the authentication call, prefixed with Bearer
X-Documaster-Error-Response-Type string custom header indicating that any error should be reported in JSON format, rather than the standard text format, should always be provided as application/json
Content-Type string content type header, always is application/json
groupId string identifier of the BSM group, groupId is a user defined value used to identify the group uniquely throught the Documaster Archive instance. The field must contain only lowercase letters, digits and dashes and must start and end with a letter.
$.groupName string name of the BSM group
$.groupDescription string description of the BSM group
HTTP Response

The operation returns HTTP 200 OK in case of success or any of the standard error codes defined.

Field Location Type Description
Content-Type string content type header, always is application/json
$.groupId string unique BSM group identifier througout the Documaster instance
$.groupName string BSM group name
$.groupDescription string BSM group description

      Request

PUT https://<documaster-instance>.local.documaster.tech:8083/rms/api/public/noark5/v1/bsm-registry/group/bsm-group-system-b HTTP/1.1
...
Authorization: Bearer {{accessTokenIntegrator}}
Content-Type: application/json
X-Documaster-Error-Response-Type: application/json

{
  "groupName": "BSM Group for System B",
  "groupDescription": "Business specific metadata to keep System B data"
}

      Response

HTTP/1.1 200 OK
...
Content-Type: application/json

{
    "groupId": "bsm-group-system-b",
    "groupName": "BSM Group for System B",
    "groupDescription": "Business specific metadata to keep System B data"
}

// Noark5Client is created and access token is provided

// Creating a BSM Group with groupId = bsm-group-system-d
BsmGroup bsmGroup = new BsmGroup("bsm-group-system-d", "BSM Group for System D");
bsmGroup.setGroupDescription("Business specific metadata to keep System D data");
bsmGroup = client.saveBsmGroup(bsmGroup);

System.out.println("BsmGroup : " + bsmGroup.getGroupId());

// NoarkClient is created and access token is provided

// Creating a BSM Group with groupId = bsm-group-system-d
MetadataGroupInfo bsmGroup = new MetadataGroupInfo("bsm-group-system-d", "BSM Group for System D", null);
bsmGroup = client.PutBsmGroup(bsmGroup);

Console.WriteLine("BsmGroup : " + bsmGroup.GroupId);

PUT /noark5/v1/bsm-registry/group/{groupId}/field/{fieldId}

The operation is used to create or update a business specific metadata field definition in a group.

The type of the BSM field cannot be changed once it is initally created.

HTTP Request
Field Location Mandatory Type Description
Authorization string access token aquired as part of the authentication call, prefixed with Bearer
X-Documaster-Error-Response-Type string custom header indicating that any error should be reported in JSON format, rather than the standard text format, should always be provided as application/json
Content-Type string content type header, always is application/json
groupId string identifier of the BSM group in which the field should be created/updated, groupId is a user defined value used to identify the group uniquely throught the Documaster Archive instance. The field must contain only lowercase letters, digits and dashes and must start and end with a letter.
fieldId string identifier of the BSM field which is to be created/update, fieldId is a user defined value used to identify the field uniquely throught the Documaster Archive instance. The field must contain only lowercase letters, digits and dashes and must start and end with a letter.
$.fieldName string name of the BSM field
$.fieldDescription string description of the BSM field
$.fieldType string type of the BSM field, possible values are string, long, double, timestamp, encrypted. Note that the type of the field cannot be changed once it is set initially.
$.fieldValues[] array list of possible values for the field
HTTP Response

The operation returns HTTP 200 OK in case of success or any of the standard error codes defined.

Field Location Type Description
Content-Type string content type header, always is application/json
$.fieldId string unique BSM field identifier througout the Documaster instance
$.fieldName string BSM field name
$.fieldDescription string BSM field description
$.fieldType string BSM field type
$.fieldValues[] array list of possible values for the field

      Request

PUT https://<documaster-instance>.local.documaster.tech:8083/rms/api/public/noark5/v1/bsm-registry/group/bsm-group-system-b/field/bsm-field-bank-account HTTP/1.1
...
Authorization: Bearer {{accessTokenIntegrator}}
Content-Type: application/json
X-Documaster-Error-Response-Type: application/json

{
  "fieldName": "Customer Bank Account",
  "fieldDescription": "BSM field for the customer's bank account",
  "fieldType": "string"
}

      Response

HTTP/1.1 200 OK
...
Content-Type: application/json

{
    "fieldId": "bsm-field-bank-account",
    "fieldName": "Customer Bank Account",
    "fieldDescription": "BSM field for the customer's bank account",
    "fieldType": "string"
}

// Noark5Client is created and access token is provided

// Creating a BSM Field with fieldId = bsm-field-bank-account in groupId = bsm-group-system-b
BsmField bsmField = client.saveBsmField("bsm-group-system-b", 
    new BsmField("bsm-field-bank-account", "Customer Bank Account", FieldType.STRING));

System.out.println("BsmField : " + bsmField.getFieldName());

// NoarkClient is created and access token is provided

// Creating a BSM Field with fieldId = bsm-field-bank-account in groupId = bsm-group-system-b
MetadataFieldInfo bsmField = client.PutBsmField("bsm-group-system-b", 
    new MetadataFieldInfo("bsm-field-bank-account", "Customer Bank Account", null, FieldType.String));
Console.WriteLine("BsmField : " + bsmField.FieldName);

DELETE /noark5/v1/bsm-registry/group/{groupId}

The operation is used to delete an existing BSM group.

HTTP Request
Field Location Mandatory Type Description
Authorization string access token aquired as part of the authentication call, prefixed with Bearer
X-Documaster-Error-Response-Type string custom header indicating that any error should be reported in JSON format, rather than the standard text format, should always be provided as application/json
groupId string identifier of the BSM group, groupId is a user defined value used to identify the group uniquely throught the Documaster Archive instance
HTTP Response

The operation returns HTTP 204 No Content in case of success or any of the standard error codes defined. No payload is provided back in case of success.

      Request

DELETE https://<documaster-instance>.local.documaster.tech:8083/rms/api/public/noark5/v1/bsm-registry/group/bsm-group-system-d HTTP/1.1
...
Authorization: Bearer {{accessTokenIntegrator}}
X-Documaster-Error-Response-Type: application/json

      Response

HTTP/1.1 204 No Content

// Noark5Client is created and access token is provided

// Delete BSM Group with groupId = bsm-group-system-d
client.deleteBsmGroup("bsm-group-system-d");

// NoarkClient is created and access token is provided

// Delete BSM Group with groupId = bsm-group-system-d
client.DeleteBsmGroup("bsm-group-system-c");

DELETE /noark5/v1/bsm-registry/group/{groupId}/field/{fieldId}

The operation is used to delete an existing BSM field in a group.

HTTP Request
Field Location Mandatory Type Description
Authorization string access token aquired as part of the authentication call, prefixed with Bearer
X-Documaster-Error-Response-Type string custom header indicating that any error should be reported in JSON format, rather than the standard text format, should always be provided as application/json
groupId string identifier of the BSM group, groupId is a user defined value used to identify the group uniquely throught the Documaster Archive instance
fieldId string identifier of the BSM field which is to be deleted, fieldId is a user defined value used to identify the field uniquely throught the Documaster Archive instance
HTTP Response

The operation returns HTTP 204 No Content in case of success or any of the standard error codes defined. No payload is provided back in case of success.

      Request

DELETE https://<documaster-instance>.local.documaster.tech:8083/rms/api/public/noark5/v1/bsm-registry/group/bsm-group-system-b/field/bsm-field-bank-account HTTP/1.1
...
Authorization: Bearer {{accessTokenIntegrator}}
X-Documaster-Error-Response-Type: application/json

      Response

HTTP/1.1 204 No Content

// Noark5Client is created and access token is provided

// Delete BSM Field with fieldId = bsm-field-bank-account
client.deleteBsmField("bsm-group-system-b", "bsm-field-bank-account");

// NoarkClient is created and access token is provided

// Delete BSM Field with fieldId = bsm-field-bank-account
client.DeleteBsmField("bsm-group-system-b", "bsm-field-bank-account");