Upgrade to Document Intelligence 3.0 or later from version 2.4 or earlier

  • Release version: Yokohama
  • Updated January 30, 2025
  • 3 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Upgrade to Document Intelligence 3.0 or later from version 2.4 or earlier

    Document Intelligence (DocIntel) 3.0 and later introduces a major upgrade transitioning from a scoped application to a ServiceNow AI Platform plugin. This upgrade includes an updated database schema and migration of data from scoped application tables (di) to new platform tables (sysdi). Proper planning and execution are essential to avoid data loss and ensure integration compatibility.

    Show full answer Show less

    Pre-Upgrade Considerations

    • Schedule upgrade timing carefully: Avoid running the upgrade during the nightly use case upgrade job to prevent delays in use case availability.
    • Update custom code: Modify any custom code referencing legacy scoped tables (di) or older DocIntel flow actions to use the new platform tables (sysdi) and 3.0+ flow actions, preferably via DocIntel APIs.
    • Add cross-scope records: For any integrations, add new cross-scope records to enable access to the new platform tables without removing existing records for the legacy tables.

    During the Upgrade

    • Avoid using Document Intelligence workspace: Refrain from extracting fields or completing document tasks until their migration to the new sysditask table is complete to prevent data loss.

    Post-Upgrade Actions

    • Test integrations and workflows: Verify that DocIntel integrations and custom workflows function correctly with the updated database schema.
    • Check for potential data loss scenarios: Be aware that actions such as deleting attachments from old records, deleting new migrated tasks, or deleting legacy process flow tasks can cause permanent data loss or broken references.
    • Migrate legacy use cases: After upgrade and data migration, rerun the scheduled “DocIntel migrate remaining data” batch job to migrate any missing legacy use cases. Use this batch job only to migrate missing data, not after deleting sysdi records.

    Cross-Scope Records

    New cross-scope records must be added to enable integrations with the new Document Intelligence platform tables. These records grant read access from the integrating business unit’s scope to various sysdi tables such as sysditask, sysdikey, sysdiocrinput, and others, ensuring seamless integration without disruption.

    Document Intelligence 3.0 or later includes an updated database schema to support its transition from a scoped application to a ServiceNow AI Platform plugin.

    Upgrade tasks

    Review the information in this topic before you upgrade to Document Intelligence (DocIntel) 3.0 or later from version 2.4 or earlier.

    For more information on installation, see Install Document Intelligence.

    Before the upgrade

    Table 1. Document Intelligence 3.0 or later pre-upgrade checklist
    Pre-upgrade task Description
    Choose a time to schedule the upgrade

    Avoid performing the upgrade during the run time of the nightly task definition (use case) upgrade job. Upgrading the application at that time would prevent use cases from upgrading until the run time of the next day.
    Update any custom code that points directly to DocIntel database tables

    After upgrading to Document Intelligence 3.0 or later from version 2.4 or earlier, DocIntel will use new flow actions. DocIntel will also use ServiceNow AI Platform database tables (sys_di_) in place of the scoped application tables (di_). All DocIntel data will be migrated automatically to these platform tables.

    Note:
    Document extraction use cases may not be available for use until the migration is complete.

    If you have custom code in your instance that points directly to the scoped application tables (di_), it should be updated, preferably to the platform component using DocIntel APIs.

    If you have custom code using DocIntel 2.4 or earlier flow actions, it should be updated to use 3.0 or later flow actions.

    For the list of tables, see Components installed with Document Intelligence.
    Add cross-scope records for integrations

    For any integrations with Document Intelligence, add cross-scope records for the new DocIntel database tables.

    Note:
    Ensure that the existing cross-scope records for the old tables are not removed.

    See the Cross-scope records section for the list of records to be added.

    For more detail on cross-scope records, see Cross-scope privilege record.

    During the upgrade

    Table 2. Document Intelligence 3.0 or later upgrade checklist
    Upgrade task Description
    Avoid using the Document Intelligence workspace to extract fields

    Wait until a document task is migrated to the sys_di_task table before completing it using the Document Intelligence workspace. Completing a task during the upgrade may lead to data loss.

    After the upgrade

    Table 3. Document Intelligence 3.0 or later post-upgrade checklist
    Post-upgrade task Description
    Test DocIntel integrations and custom workflows

    Test your use case integrations to ensure they function with the new database schema.
    Check for data loss

    Some cases where you can lose data include:

    • Any action resulting in the attachment deletion in an old di_task record would result in a missing attachment for the new sys_di_task record.
    • Deletion of any new tasks created during the data migration (that is, during or right after the 3.0 or later upgrade) would result in permanent deletion as those records might not have entries in di_task tables.
    • Deletion of an old “process_task” flow (or any action resulting in that flow deletion) would result in an empty flow reference in the new integration setup records.
    Post-upgrade migration of legacy use cases imported through update sets

    At any time after the completion of the Document Intelligence 3.0 or later upgrade and data migration, you can rerun the migration batch script that ran during the upgrade.

    You may want to run this script if you must migrate any imported use cases requiring migration to the platform tables (sys_di_).

    1. Navigate to All > System Definition > Scheduled jobs.
    2. Open the DocIntel migrate remaining data scheduled job.
    3. Select the Active check box.
    4. Select Execute Now.
    Warning:
    Never use the DocIntel migrate remaining data batch job to rerun migration after deleting all records from sys_di tables. You should only use it to migrate missing data from di_ tables to sys_di tables.

    Cross-scope records

    Table 4. Cross-scope records for Document Intelligence 3.0 or later
    Source scope Target scope Target name Operation Target type Status
    Scope of integrating BU global sys_di_task Read Table Allowed
    Scope of integrating BU global sys_di_key Read Table Allowed
    Scope of integrating BU global sys_di_key_group Read Table Allowed
    Scope of integrating BU global sys_di_ocr_input Read Table Allowed
    Scope of integrating BU global sys_di_pdf_input Read Table Allowed
    Scope of integrating BU global sys_di_prediction_input Read Table Allowed
    Scope of integrating BU global sys_di_training_input Read Table Allowed
    Scope of integrating BU global sys_di_key_hint Read Table Allowed