ACRM/CRM.web: Show Custom Fields in a One-Off Document Upload Dialog Using a Custom <code>expandName</code>

Solution

Scenario

You need a one-off custom document upload dialog in ACRM/CRM.web that shows additional fields (for example, two catalog fields) without changing the global/default upload dialog (for example, without modifying D1.Upload or global settings such as D1.Upload.details).

Symptoms / How to Recognize It

• The upload dialog opens, but the additional fields from your custom configuration do not appear.
• CRM.web console/network shows the default expand being used, for example expandName:"D1.Upload" in the ExpandChannel.Get payload.
• If the documents.upload(...) call is structured incorrectly, you may see this exact exception:
  • Exception: Error:In order to upload a document you must specify a uid, a documentKey or an info area id!; uid=u8.Base/Error/99

Root Cause

1. u8.services.documents.createDocument(...) cannot switch the upload dialog via expandName.

   Passing expandName to createDocument does not change which upload fields are shown, so the UI continues to use the default upload configuration.

2. u8.services.documents.upload(...) has two simultaneous requirements.

   • Top-level validation requirement: the object passed to documents.upload(...) must include one of:

     • uid, or
     • documentKey, or
     • infoAreaId

   • Upload widget configuration requirement: the upload popup applies UI options (including expandName) from a nested object:

     • upload: { ... expandName ... }

3. If expandName is not inside upload:{...}, the upload UI falls back to the default (commonly D1.Upload). If everything is placed only under upload:{...} and the top-level options omit uid/documentKey/infoAreaId, the call fails immediately with the validation exception shown above.

Resolution (One-Off Upload Button/Action)

1) Prepare the CRM.Designer Configuration

• Create (or confirm) a D1 expand configuration and underlying field group that contains the extra catalog fields you need.
• Use the base expand name for runtime references (do not reference the .details suffix as the runtime name).
• Example naming pattern: D1.<custom_upload_expand_name>

2) Use u8.services.documents.upload(...) with Correct Nesting

Provide a top-level infoAreaId (to satisfy validation) and keep expandName under upload:{...} (so the upload widget applies it):

myNamespace.customDocumentUpload = function (args) {
  u8.services.documents.upload({
    infoAreaId: "D1",
    upload: {
      linkUid: { infoAreaId: "<linked_info_area_id>", recordId: args.uid.recordId },
      allowMultiple: false,
      expandName: "D1.<custom_upload_expand_name>"
    }
  }, function (sender, result) {
    // result.uid = uploaded document uid
  });
};

Notes:

• Keep values quoted as strings (unless you intentionally pass variables).
• linkUid should point to the record you want the uploaded document to be linked to (replace <linked_info_area_id> appropriately).

3) Invalidate CRM.web Cache After Configuration Changes

After adding or changing upload-related configuration in CRM.Designer, invalidate the CRM.web cache so clients load the updated configuration. UI configuration changes commonly require cache invalidation before they take effect.

Verification

1. Click the one-off upload button/action.
2. Check CRM.web network/console for the ExpandChannel.Get payload.
3. Confirm it now uses your custom expand name:
   • Expected: expandName:"D1.<custom_upload_expand_name>"
   • Not expected: expandName:"D1.Upload"
4. Confirm the upload dialog displays the additional catalog fields and that the document upload completes successfully.