Publishing Individual Records Using a Custom Object

The custom object serves as a publish button, which references the Engage fields in your questionnaire or your application and publishes them to Engage.

Use either the process described below, or the Engage tab in the Application Builder.

Important: Download and install the Archer_6.9_P3_Engage_Template_Package.zip available on the Community. This package provides an examples of applications and questionnaires that work with Engage, including a custom object code example.

Note: When preparing a questionnaire or application for internal users, we recommend using the custom object method.

Task 1: Verify fields in the Contacts application exist and capture relevant field IDs

Important: This step is required for E4V, which only supports cross-references. E4BU supports cross-reference, record permissions, and user/groups.

Note: The Contact section can be populated with a Contact, User/Group, or Record Permission. If you use a Contact cross-reference, all of the field ID names in the Contact section must be accurate. If you use a User/Group or Record Permission, only the ContactFieldId needs to be populated with the field ID of the User/Group or Record Permission.

Complete this task if you are using a Contacts field for your Engage users. If you use a User/Groups or Record Permissions field, you can skip this step.

1. From the menu, click > Applications, select Contacts.

2. In the Objects panel, click to enter the full screen view.

3. Click and select ID. Locate and document the field IDs for the following Archer fields.

   Note: If you are using a record permission or user/groups field, you must still include all of these fields, but it is not used to populate the participant information. The participant information is populated from the user profile record.

   • Firstname

   • LastName

   • Email (Business)

   • JobTitle

Task 2: Create new fields

Edit the default layout in your application or questionnaire to add a new Engage section containing fields and a custom object required to publish.

1. Open the default layout in the application or questionnaire you want to publish.

   1. From the menu, click > Application Builder > Applications.

   2. Select the application or questionnaire.

2. Click the Designer tab.

3. On the Default Layout, to create a new section for the Engage fields, do the following:

   1. In the Objects pane, from the Layout Object section, select Section and drag and drop it where you want it to appear on the layout.

   2. Enter a section name, such as Engage Details.

   3. Click Save.

4. Repeat the following step for each field described in the table below.

   In the Objects pane, from the Data Fields section, click Add New.

   1. Select the field type.

   2. Enter the field name.

   3. Click Create Field.

   4. Drag and drop new fields from the Objects Panel to the Layout Builder where you want them to appear in the new section.

   5. Click Save.

   Repeat step 4 for each of the fields described in this table.

   Field	Type	Description
   Additional Guidance	Text	This field supplies additional instructions for the Engage participant in the Instructions section of the request page.
   Contact Name	Text	This field supplies a contact name from your organization, which is sent in the email notification to the Engage participant. Note: This field is required.
   Contact Email Address	Text	This field supplies a contact email address from your organization, which is sent in the email notification to the Engage participant. Note: This field is required.
   Due Date	Date	This field represents the due date within Engage. Note: This field is required.
   Engage Status	Values List	This field tracks the current record status between your Archer instance and Engage. This field is automatically set and is used to prevent duplicate publishing. You must tie this field to the Portal Status global values list. Note: This field is required. Note: If you do not have the Portal Status Global Values List, it is available in the Third Party Risk Management use case or in the Archer 6.6 P5 Engage Template Package.zip on Archer Community.
   Publish Message	Text	This field contains messages that are returned by the publish and sync actions from the Engage Agent.
   Company Name	Text	This field identifies the company that is requesting information from the Engage participant. This field is used in both the email notifications and the Engage record. You may want to make this a calculated field to hold a static value. Note: This field is required.
   Engage Contacts	Cross-reference, record permissions, or user/groups	This field identifies the users who are the initial participants for the Engage record. Note: This field is required and cannot be a calculated cross-reference field. Important: E4V only supports Cross-references. E4BU supports Cross-reference, record permissions, and user/groups. Important: User/Groups or Record Permissions field, only users can be selected, not groups. All users must have an email address linked to their Archer account to create an account within Engage.
   HistoryField	Sub-Form	(Optional) This field is used to track the assessment submitter's details, like the email ID and the submission date. Important: Before you add this field, create a sub-form that contains the following fields: Action By (text) Action (text) Action Date (date and time)
   IdentifierField	Tracking Id/Text/Numeric/Date	(Optional) This field identifies the individual request sent to internal or external users. If you want to use the application/questionnaire's key field as the identifier field, do not use this field. Note: Masks for text field are not supported. Note: If you are using a calculated field as the identifier field, ensure calculations are done on the record before publishing it. Else the content ID for that record will be treated as the request identifier.
   Publish Language	Values List (Single Selection)/Single line text field	(Optional) Request content is displayed in this language on the Engage Portal. When using Single line text field ensure you enter a single language name. Note: Ensure this language is available in your Archer instance. The language string in this values list should exactly match the string in the columnlanguage_nameof the database table tblLanguage.
   Portal Request URL	Text or URL	(Optional) Select the application or questionnaire field to receive the unique engage request on successful publication.
   Visible Fields	Numeric	(Optional) The number of non-read only fields visible to the Engage user on the portal. Note: Do not map this field with a calculated field, read-only field, or a Numeric Question field.
   Engage Progress	Numeric	(Optional) Progress in percentage made by the portal user on the request based on the visible fields. Note: Do not map this field with a calculated field, read-only field, or a Numeric Question field.
   Required Fields Remaining	Numeric	(Optional) The number of required fields remaining to be answered for a portal user to submit the request. Note: Do not map this field with a calculated field, read-only field, or a Numeric Question field.

Task 3: Create a new Engage layout

Create a separate layout on the application or questionnaire that contains only the fields and objects you want to publish to the Engage portal.

Important: You must enable Advanced Workflow to allow multiple layouts on an application or questionnaire, but you do not have to configure the workflow.

1. In your application or questionnaire, go to the Advanced Workflow tab, click Create Workflow, and then click the Designer tab. Confirm that you are on the Default Layout.

2. Click the Layout menu, select Copy Current, type in a name, and click Copy Layout.

3. In the Properties panel,

   1. Enter the layout name and description.

   2. Click to enter the full screen view. Locate and document the ID. This is your LayoutID.

4. (Optional) In the Layout Builder, remove any fields or sections that do not belong in the Engage record, including unsupported field types. The Engage layout only needs to contain the fields you want in the Engage record. However, if you leave unsupported fields on the layout, the system ignores them during the publishing process.

5. On the Objects panel, click to enter the full screen view.

6. Click and select ID. Locate and document the field IDs for the following fields:

   • Additional Guidance

   • Requesting Party Email Address

   • Requesting Party Name

   • Due Date

   • Engage Status

   • Publish Message

   • Company Name

   • Engage Contacts

   • History Field (Optional)

   • IdentifierFieldId (Optional)

   • Publish Language (Optional)

   • Portal Request URL (Optional)

   • Visible Fields (Optional)

   • Engage Progress (Optional)

   • Required Fields Remaining (Optional)

7. Click Save.

Task 4: (Optional) Collect Field IDs from the History Field sub-form

Note: Only E4BU supports the history log.

To configure the custom object, you need the Field IDs for several fields on your questionnaire. This task walks you through how to obtain them.

1. (Optional) Obtain the field IDs for your history field sub-form.

   1. From the menu, click > Applications, select your history field sub-form, and click the Designer tab.

   2. In the Objects panel, click to enter the full screen view.

   3. Click and select ID. Locate and document the field IDs for the following Archer fields.

      • Action By (text field)

      • Action (text field)

      • Action Date (date and time field)

Note: To send this questionnaire to multiple recipients at once, go to Publishing records in bulk using a data feed after completing these first 4 tasks.

Task 5: Configure the custom object code

If you use the provided custom object code, you must edit it to ensure that the code is referencing correct field IDs. Before you configure the code, you must have the field and layout IDs from the Contacts application, the application or questionnaire that you want to publish content from, and the optional history sub-form. You gathered these field IDs in previous steps.

The field IDs entered in custom object are also used to populate invitation emails. These values are the only customizable objects within the email template.

In this custom object code, the identifier field is the default key field for the application or questionnaire. To use a different field, configure the IdentifierFieldId within the custom object. This field supports text, numeric, date, and tracking ID field types. Masks for text field are not supported.

If your record contains calculated fields and you publish before the Engage and Archer complete synchronization, the published calculated fields are blank.

1. To create the custom object on the layout that represents a Publish button, do the following:

   1. From the Add New Layout Object drop-down menu in the left pane, select Add Custom Object and drag and drop it where you want it to appear in the new section.

   2. Enter a name for the custom object, such as Publish Button.

   3. In the Code field, paste the custom object code obtained from the community. Modify this custom object code based on your setup according to the updates in the following file:

      Publishing_Custom_Object_Customization.txt

   4. (Optional) For existing customers already using the custom object.

      If you want the custom object Publish button label to be in sync with the Portal status, do the following:

      1. Download the latest custom object code from the community, open this file, and copy everything starting from the <style> tag.

      2. Open the custom object code file that you are locally using on your machine and locate the <style> tag.

      3. Replace all the custom object code in Task 5 Step 1d(ii) starting from the <style> tag with the custom object code you copied in Task 5 Step 1d(i).

      4. Update the instanceName as per your setup in the following line of the custom object code:

         let instanceName ="Archer";

   5. Click OK.

2. Edit the custom object code, as follows:

   1. In the Layouts tab, select Default Layout.

   2. Click the Designer tab.

   3. In the Engage Detail section, click the arrow next to the name of the custom object, for example, Publish Button.

   4. Select Edit Custom Object Properties.

   5. Do one of the following:

      1. In the Code field, locate the jsonRequestBody. This is the same code you copied in step 1.

      2. Update the ID for each application or questionnaire where your custom object is applied. For example, update the numerical value after LayoutID with the value you collected in task 3.
         

         Important:  The Contact section can be populated with a Contact, User/Group, or Record Permission. If you use a Contact cross-reference, all of the field ID names in the Contact section must be accurate. If you use a User/Group or Record Permission, only the ContactFieldId needs to be populated with the field ID of the User/Group or Record Permission.

      3. (Optional) Update the fields for the History Log.

         Note: If the History sub-form is not used, set the value of HistoryFieldId to 0 in the custom object or delete all the History sub-form fields from the custom object.

      4. Update the ProductIdentifier with either E4V or E4BU depending upon the product you are using.

      5. (Optional) If you want to send notifications through Engage, ensure IsEngageNotificationRequired is set to true.

      6. (Optional) If you want to enable comments through Engage, ensure IsCommentsEnabled is set to true.

   6. Review the JSON data file to ensure all IDs are valid.

   7. After updating the values, click OK.

   8. Save the application.

Task 6: (On-Premises Only) Configure the directory location in the custom object code

By default, Archer is installed in the Archer directory under Default Web Site in Microsoft Internet Information Services (IIS). If you installed Archer in a different sub-directory, you must configure the custom object code to reflect the location of your Archer installation.

Important: The URL must reflect the value you set while configuring the Server Farm.

For more information, see Publish URLs.

For example, if you installed Archer in the MySite sub-directory, you must revise the line in the custom object code as follows:

Default (from the example Custom Object): const portalURL = '/engage/api/questionnaire/Publish';

Default Installation Location: const portalURL = '/Archer/engage/api/questionnaire/Publish';

Revised Installation Location: const portalURL = '/MySite/engage/api/questionnaire/Publish';

Note: The sub-directory name is case sensitive.

In both of the above examples: 

1. Open the custom object code.

2. In the Code field, locate the following text:

   const portalURL ='/engage/api/questionnaire/Publish';

   1. (Optional) specify a specific API version in the url: portalURL = '/engage/api/v1/questionnaire/Publish';

      Current version is v1

3. Update the code as needed.

4. Click OK.

5. Save the application.

Task 7: Create data driven events

We recommended that you create data driven events (DDEs) to hide the custom object until all required fields are populated to prevent users from reaching an error state. For example, you might create a new calculated field, "Required Engage Fields Populated," that returns a Yes or No response, depending on whether all of the required fields you created have been populated. You could then create a "Show Publish Button" DDE that displays the Publish Button when the value of "Required Engage Fields Populated" is Yes.

For more information, see "Data Driven Events" in the Archer Platform Help.