# Configuring the Material ID Document Field (PromoMats)

Using the _Material ID_ document field, Vault can track the document number and revision in an automatically generated unique ID number on the Promotional Material. Users can easily identify the steady state version for audit and compliance purposes and for submissions to health authorities. Vault updates the _Material ID_ each time the document moves from a _Steady State_ to _Draft_, often at the same time as Vault upversions the document, such as from version 2.0 to 2.1. This improves compliance and tracking for content update and reuse.

The _Material ID_ field is beneficial for both eCTD and non-eCTD submissions.

To use the _Material ID_ field, you must configure the _Material ID_, _Revision_, and _Update_ fields on the Material doc type. If you are generating [eCTD Compliance Packages,](/en/lr/65734/) you'll also need to add the _Promotional  Material ID_ field to the _Clean Material_ document type.

To configure the _Update_ field:

  1. Navigate to **Admin > Configuration > Document Fields**.
  2. Under _Field Location_, select **Material**.
  3. Click **Add** and select **New Field** to [create a custom document field](/en/lr/592/).
  4. Configure the new document field as follows:
      * Field type: **Yes/No**
      * Label: **Update**
      * Set the **Do not copy this field during Make a Copy** checkbox
      * Display Section: **Submission Details**
      * Default Value: **No**
      * Help Content: **Update Material ID and Revision fields on next state change if the Update field = Yes**
  5. Click **Save**.
  6. Under _Material_, select the new **Update** field.
  7. Click the **Security Overrides** tab and set the _Default Security_ to **Read Only**.

After creating the _Update_ field, configure document fields and the _Material_ lifecycle:

  1. Navigate to **Configuration > Document Fields**
  2. Under _Field Location_, select your Promotional Material document type. By default, this is **Material**.
  3. Click **Add** and select **Existing Shared Field**.
  4. Add the following fields:
      * **Material ID**
      * **Update**
      * **Revision**
  5. Repeat steps 2 – 4 to add the **Promotional Material ID** field to the **Clean Material** document subtype. Note that you should not add the _Material ID_, _Update_ and _Revision_ field to the _Clean Material_ document type.

If you are using the PromoMats & RIM Vault connection, you'll also need to perform the following steps:

  1. Navigate to **Configuration > Document Fields**.
  2. Under _Field Location_, select **eCTD Submission Ready Documents**, then expand **Submission Ready Copies**.
  3. Select **Annotated Material**.
  4. Click **Add** and select **Existing Shared Field**.
  5. Select **Promotional Material ID**.
  6. Click **OK**.
  7. Repeat steps 3 – 6 with the following document classifications: _Annotated Label_, _Annotated Reference_, and _Clean Material_.

Next, add [event actions](/en/lr/51700/) to the _Material_ lifecycle:

1. Navigate to **Configuration > Document Lifecycles > Material > Event Actions**.
2. Open **Create Document** event and click **Edit** to add the following event actions:
    * Always update document field **Revision**, set to value **1**.
    * Always update document field **Material ID** to **`Document.document_number__v & "-1"`**.
3. Click **Save** and return to the **Event Actions** tab.
4. Open the **Create Draft** event and click **Edit** to add the following event actions:
    * If document field **Update** equals **Yes**, perform actions** update document field** **Revision** set value to **`If(IsBlank(Document.revision__v), 1, Document.revision__v + 1)`**.
    * If document field **Update** equals **Yes**, perform actions** update document field** **Material ID** set value to **`Document.document_number__v & "-" & Text(Document.revision__v, "#")`**.
    * If document field **Update** equals **Yes**, perform actions **update document field** **Update** and set value to **False**.
5. Click **Save** and return to the **Event Actions** tab.
6. Open the **Create Copy** event and click **Edit** to add the following event actions:
    * Always update document field **Revision**, set to value **1**.
    * Always update document field **Material ID** to **`Document.document_number__v & "-1"`**.
7. Click **Save.**

To update the _Material_ lifecycle:

  1. Navigate to **Configuration > Document Lifecycles > Material > States**.
  2. Open the **Draft** state.
  3. Click the [**Entry Actions**](/en/lr/12399/#create) tab and click **Edit** to add the following new rule:
      * **Perform with conditions**
      * If _Update_ equals _Yes_, **Update Revision and Material ID** and _Set field using formula_ **Update** equals **false**.
  4. Click **Save** and return to the **States** tab.
  5. Open the steady state. By default, this is the _Approved for Distribution_ state.
  6. Add the following rule:
      * **Always**
      * Set field using formula **Update** equals **true**.
  7. Click **Save**.

Finally, if you're creating eCTD Compliance Packages, update the Correspondence Letter, XML elements, and the lifecycle your Promotional Material is using. By default, Promotional Materials are included in the _Material_ lifecycle.

To update the [Correspondence Letter](/en/lr/65733/#correspondence-letters):

  1. Open the Correspondence Letter template document.
  2. In the _Material ID_ section, add the following **Promotional Material ID** token to allow Vault to populate the unique ID number: **`${vault:document_promotional_material_information__vr.documents__vr.promotional_material_id__v}`**.
  3. Navigate to **Business Admin > Templates > Documents & Binder > eCTD Submission Ready Documents > Correspondence Letter**.
  4. Click [**Edit**](/en/lr/5509/).
  5. Click **Upload File** and select the edited Correspondence Letter template file.
  6. Click **Save**.

To update the [XML elements](/en/lr/65733/#xml-elements):

  1. Navigate to **Business Admin > Objects > XML Elements**.
  2. Open the  **Input 7.d Material ID Code** record and click **Edit**.
  3. Enter **`DocInBinder.promotional_material_id__v`** in the _Formula_ field.
  4. Click **Save**.
  5. Repeat steps 2 – 5 for the **Input: Document Row: Doc Number Input** record.


## Promotional Material Document Name and Description Fields

You can configure eCTD Compliance Packages to use the _Promotional Material Document Name_ and _Description_ fields. You can add these fields to the [Correspondence Letter](/en/lr/65733/#correspondence-letters) and 2253 and Supplementary Forms.

You'll first need to add the fields to several document types:

  1. Navigate to **Configuration > Document Fields**.
  2. Under _Field Location_, select **eCTD Submission Ready Documents**, then expand **Submission Ready Copies**.
  3. Select **Annotated Material**.
  4. Click **Add** and select **Existing Shared Field**.
  5. Select **Promotional Material Document Name**.
  6. Click **OK**.
  7. Repeat steps 3 – 6 with the following document classifications: _Annotated Label_, _Annotated Reference_, and _Clean Material_.

Next, you'll need to update XML elements for the 2253 and Supplementary Forms:

  1. Navigate to **Business Admin > Objects > XML Elements**.
  2. Click **7. e. Material Description**.
  3. Click **Edit.**
  4. In the _Formula_ field, enter **`DocInBinder.promotional_material_doc_name__v`**.
  5. Click **Save**.
  6. Return to **Business Admin > Objects > XML Elements**.
  7. Click **Document Row: Document Name Input**.
  8. Click **Edit**.
  9. In the _Formula_ field, enter **`DocInBinder.promotional_material_doc_name__v`**.

<div class="note-border alert-info">
  <div class="alert alert-info" role="alert">
    <div><i class="far fa-info-circle"></i></div>
    <div class="alert-text">
      <p><strong>Note</strong>: You can also use the <em>Promotional Material Document Description</em> field in place of the <em>Promotional Material Document Name</em> field. When updating the document fields on document classifications, add the <strong>Promotional Material Document Description</strong> field instead of the <em>Name</em> field. For the XML elements, add the <strong><code class="language-plaintext highlighter-rouge">DocInBinder.promotional_material_doc_description__v element instead</code></strong>.</p>
    </div>
  </div>
</div>



Finally, you'll need to replace the **Material Description** formula in the [Correspondence Letter template](/en/lr/65733/#correspondence-letters) with **`${vault:document_promotional_material_information__vr.documents__vr.promotional_material_doc_name__v}`**.


## FAQ

### Can I hide the _Update_ field?

No. If you hide the _Update_ field, the feature will not work.

### Can I change the _Material ID_ or _Revision_ values?

By default, these fields are set to _Read Only_. We recommend keeping _Material ID_ and _Revision_ as _Read Only_ fields to ensure the values remain unique. However, Admins can make these fields _Editable_ if necessary. Note that editing these fields may result in ID numbers that are non-sequential or non-unique. For example, if a user manually updates a document's _Material ID_ field from US-23456-2 to US-23456-7, when the entry or event action occurs, Vault will automatically overwrite the edited _Material ID_ field and update both the _Revision_ and _Material ID_ field to _3_, resulting in an ID number of US-23456-3.

### Will configuring this feature affect documents created previously?

Extra configuration is required to update the fields on existing documents. Navigate to **Configuration > Document Lifecycles > Material > Event Actions > Create Draft > Entry Actions** and add the following entry actions: If _Update_ is blank, update field _Revision_ with value `Document.major_version_number__v + 1`, update field _Material ID_ with value `Document.document_number__v & "-" & Text(Document.revision__v, "#")`, and update field _Update_ with value `false`.

### If I reclassify a document to a document type with the _Material ID_ and _Revision_ fields, are the values updated immediately?

No. The _Material ID_ and _Revision_ fields are only populated when the configured entry actions or event actions occur.