How to register a document

Registering documents in the system allows you to place app items in the company’s document categorization scheme and assign it a registration number. To register app items in folders, you need to set up registration and configure the document categorization scheme. Custom scripts allow you to obtain lists of folders and register app items in folders created in the Document categorization workspace and reserve registration numbers for them.

Register an app item

You can use a custom script to register a document in all folders selected in the app’s settings. To do that, we need to get the IDs of all folders that the app item can be registered in. First, we need to find the app item. To do that, you can either use the context or the Global and Namespace global constants.

Example of getting an app item from the context:

    // Getting an item stored in the context
    const agreement = Context.data.agreement!;

Example of getting an app item in search using the Global constant:

// Getting an item using search
const agreement = Global.ns.documents.app.agreement.search().first();

To register a document using a custom script, you need to pass the folder’s ID to the DocflowApplicationItemRef.register method. You can get the folder’s ID from RegistrationSettings.nomenclatureIds. This property stores all folders available for the app item. This can be used to get a list of folders available for the app item we obtained in the previous step:

// Getting settings
const settings = await agreement.getSettings();

// Getting folder IDs
// They can later be used for registration
const registrationIds = settings.registrationSettings.nomenclatureIds;

Then you can use the IDs you obtain to register the document in all the available folders:

// The app item is registered in all the available folders
const registrations = registrationIds.map(registerId => agreement.docflow().register(nomenclatureId))
// Waiting until all registrations are completed
const registrationsResult = await Promise.all(registrations);

// Checking that all registrations are successful
const allRegistrationsCompleted = registrationsResult.every(registrationResult => registrationResult);
if (!allRegistrationsCompleted) {
    // If not all registrations are completed successfully, the script is interrupted
    throw new Error('The document is not registered');
}

Registration number reservation

A company may have a document numbering procedure that sets an order of numbers different from the one in custom scripts or business processes. In this case, you can use reservation of registration numbers. To reserve a document registration number before actual registration, use the DocflowApplicationItemRef.reserve method. It allows you to get a reserved number for an app item.

You can cancel number reservation using DocflowApplicationItemRef.deleteReservation.

Here is an example of using these methods to reserve a registration number and cancel reservation:

// App stored in the context
const item = Context.data.document!;
// Getting the app’s settings
const settings = await item.getSettings();
const nomenclatures = [];

// Getting information about folders available for registration in the app
for (const nomenclatureId of settings.registrationSettings.nomenclatureIds) {

    const nomenclature = await item.docflow().getNomenclature(nomenclatureId);
    if (nomenclature !== undefined) {
        nomenclatures.push(nomenclature);
    }
}

// Search for the folder in which a number needs to be reserved
const nomenclatureName = 'Folder name';
const nomenclatureForReservation = nomenclatures.find(nom => nom.name === nomenclatureName);

if (nomenclatureForReservation !== undefined) {
    // If the folder for number reservation is found, a registration number for the app item can be reserved
    const reservedNumber = await item.docflow().reserve(nomenclatureForReservation.__id);
}