BeyondERP.Newsletter
Menu

Job page · System administration

Custom scripts

A list page where you upload, approve, test and run deployable packages that contain custom X++ scripts, without downtime.

Business process
Administer system features
Menu item
AppConsistencyCustomScriptListPage
Main table
AppConsistencyCustomScript
Setup steps
1 on this page
Show what matters for
PAGE GUIDEWhat the page does and how to use it8 sections. Choose a role to highlight what matters to you.
Everyone

1What it is and why

What it isA list page where you upload, approve, test and run deployable packages that contain custom X++ scripts, without downtime.
What you do hereUse this page to correct minor data inconsistencies, of about ten records at most, without disruptive downtime.
ExampleFor example, three BEAT sales lines carry a wrong reference; a developer uploads a package whose script asserts the company and that exactly three rows change, a second user approves it, the test log shows three rows, and the script is run and marked Purpose resolved.
Custom scripts page in Dynamics 365
The page in Dynamics 365. page title tab to open what to set or check
Functional consultant · Solution architect

2Where it fits

Business processAdminister system features
Menu pathSystem administration › Periodic tasks › Database › Custom scripts
Set up firstAssign users to roles (two trusted users with the two duties) Microsoft Learn
Used next byDatabase Log (review the changed records) Microsoft Learn
Related pagesData maintenance Microsoft Learn
End user · Functional consultant

3How to do it

About the examples: Examples and screenshots in this guide use BEAT, a demo company in a Dynamics 365 test environment. Use your own company's codes and values instead of copying them.

When to run it

When to run itWhen a handful of records (about ten at most) are inconsistent and can't be corrected through normal business processes or other self-service tools.
How oftenOn demand, once per data issue.
What the output showsAn event log for each script with who uploaded, approved, tested and ran it and when, plus the script details that show which entities were touched. A test log that shows more changed records than expected means the script must not be run.

Source: Microsoft Learn

Setup steps on this page

Correct a few records with an approved custom script

Fix about ten inconsistent records without downtime, with approval and a test run.

Steps from Microsoft

  1. Go to System administration > Periodic tasks > Database > Custom scripts.
  2. Select Upload, choose the deployable package that contains exactly one runnable X++ class, and state the purpose of the script.
  3. Have a different user open Details and select Approve or Reject; the person who uploaded the script can't approve it.
  4. Select Run test. The script runs in a transaction that is rolled back while logs are collected; select Accept test log if the result is right, or Abandon if it isn't.
  5. Select Run to run the script for real, then select Purpose resolved or Purpose unresolved. Either choice locks the script.

Source: Microsoft Learn

Fields on the page

FieldWhat it means
Approve / RejectApproval unlocks the script for testing; rejection locks it.Microsoft Learn
Run testRuns the script in a transaction that is rolled back, while logs are collected.Microsoft Learn
Purpose resolvedRecords success; the script is then locked and can't run again.Microsoft Learn
UploadUploads a deployable package with exactly one runnable X++ class and asks for the purpose of the script.Microsoft Learn
Accept test log / AbandonAccept test log allows the script to run; Abandon stops it for good.Microsoft Learn
Purpose unresolvedRecords that the script didn't fix the issue; the script is locked and nothing is undone automatically.Microsoft Learn

Common errors and fixes

MessageWhat to do
The uploader can't approve the scriptBy design: a different user must approve. Give the Approve custom scripts duty to a second trusted user. Microsoft Learn
The test log shows more records than expectedSelect Abandon. Learn advises asserting the expected number of affected records in the script and changing about ten records at most. Microsoft Learn

Test checklist

  1. The test log shows only the records you meant to change.
  2. After Run, the corrected records look right and dependent business processes complete.
  3. The script ends in Purpose resolved and is locked.

Source: Microsoft Learn

Functional consultant

4Setup decisions

Setup stepRecommended value and whyDecision, common mistake and test
Correct a few records with an approved custom scriptGive Maintain custom scripts and Approve custom scripts to two different trusted users, test every script outside production first, and only change about ten recordsLearn: the uploader can't approve their own script, every package needs a test run, and the feature is for minor corrections of roughly ten records only.Who uploads and who approves custom scripts?Using a script for data migration or long-running fixes, or bypassing business logic with doUpdate, doInsert or doDelete.Test: A script needs a second user and a test

Feature management and licence

Licence or add-inOn this system the page opens for Approve custom scripts and Maintain custom scripts. It needs the Maintain custom scripts and Approve custom scripts duties on at least two trusted users. No Feature management feature needs to be turned on for this page.

Microsoft Learn

Solution architect

5Design impact

Shared or per companyThe script runs in the company context it is started in; Learn advises the script to assert the company, for example by throwing an error if it isn't DAT. Microsoft Learn
Can it be undoneNo: A script that ran isn't undone automatically. You may need to write and run another script to reverse its effect. Microsoft Learn
If you change it laterA script that didn't work isn't undone automatically; you may need to run another script to reverse it. Microsoft Learn
Technical architect

6Technical

Menu itemAppConsistencyCustomScriptListPage Checked in Dynamics 365
FormAppConsistencyCustomScriptListPage Checked in Dynamics 365
TableAppConsistencyCustomScriptChecked in Dynamics 365
Who can open itPrivilegesApprove custom scripts AppConsistencyCustomScriptApproveMaintain custom scripts AppConsistencyCustomScriptMaintainDutiesApprove custom scripts AppConsistencyCustomScriptApproveMaintain custom scripts AppConsistencyCustomScriptMaintain
2 security roles AppConsistencyCustomScriptApprover AppConsistencyCustomScriptMaintainer
Checked in Dynamics 365
Roles to set it up and use itTo set it up or change itApprove custom scripts AppConsistencyCustomScriptApproveMaintain custom scripts AppConsistencyCustomScriptMaintainGive people a role that holds these duties. On this system, 2 roles give access to this page.Checked in Dynamics 365
Actions on the pageOptions: Page options, ShareChecked in Dynamics 365
Developer

7Developer

Open it by URLhttps://<your-environment>/?mi=AppConsistencyCustomScriptListPage
Data migrationLoad order: Custom scripts has no data entity in Data management, so it can't be loaded from a file or a configuration template. It is a one-time correction tool and must not be used for data migration; upload the package again in the environment where the data must be corrected.Microsoft Learn
Everyone

8Sources