Publishing Records in Bulk Using a Data Feed

This method uses a JavaScript transporter data feed to send invitations to multiple recipients at once, instead of having to manually click a button for each recipient.

For example, you want to send a device assessment to all your employees with devices.

Prerequisites

1. You must have the ability to run data feeds in your environment.

   If you are in a hosted or SaaS environment, you need the digital thumbprint of the signed JavaScript that is loaded against your instance. This is also required if you are using an on-premises environment that requires signed thumbprints. See task 1 for instructions.

2. Complete tasks 1 through 4 in Publishing Individual Records Using a Custom Object, to create the required fields and layout that are needed to publish.

3. Verify that your application or questionnaire has a tracking ID field. If not, create 1.

4. 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.

Task 1: (On Premises Only) Obtain a certificate thumbprint

This task is not required if you are in a hosted or SaaS environment. This task is required only if you are using an on-premises environment that requires signed thumbprints.

1. On the Web Server and Services Server machines, do the following:

   1. Launch "certmgr" from the Start menu.

   2. Navigate to Certificates - Local Computer > Trusted Root Certification Authorities > Certificates.

   3. Ensure that the following certificates are in the Certificates sub-folder of the Trust Root Certification Authorities folder: Archer Technologies LLC

2. Verify that the certificate is trusted:

   1. Double-click the Archer Technologies LLC certificate.

   2. In the Certificate window, click the Certification Path tab.

   3. Ensure that the Certificate Status window displays the following messages: "This certificate is OK."

      Note: If the Certificate Status windows displays something different, follow the on-screen instructions.

3. Obtain the trusted certificate thumbprint.

   1. In the Certificate window, click the Details tab.

   2. Scroll to and select the Thumbprint field.

      The certificate's digital thumbprint appears in the window.

   3. Copy the thumbprint.

      For information on adding digital thumbprints, see "Configuring JavaScript Transporter Settings" in the Archer Platform Help.

Task 2: Create a calculated field for the JSON body

This field calculates the JSON body that needs to be passed to the Publish API.

1. In your source application or questionnaire, create a new calculated text field. For instructions, see "Adding Calculated Fields" in the Archer Platform Help.

   The formula should match the following example, with your field and layout IDs substituted for the sample values.

   CONCATENATE(

   "{""Contact"":{",

   """ContactFieldId"":27426,",

   """FirstNameFieldId"":531,",

   """LastNameFieldId"":543,",

   """EmailFieldId"":579,",

   """JobTitleFieldId"":544},",

   """LayoutId"":926,",

   """RequestingCompanyNameFieldId"":27409,",

   """DueDateFieldId"":27378,",

   """HelpTextFieldId"":27415,",

   """ArcherContactNameFieldId"":27411,",

   """ArcherContactEmailFieldId"":27412,",

   """StatusFieldId"":27414,",

   """PublishMessageFieldId"":27413,",

   """VendorNameFieldId"":27410,",

   """IdentifierFieldId"":27417,",

   """ProductIdentifier"":""E4V"",",

   """PublishLanguageFieldId"":27416,",

   """PortalRequestURLFieldId"":27418,",

   """IsEngageNotificationRequired"":true,",

   """IsCommentsEnabled"":true,",

   """VisibleFieldsFieldId"":27419,",

   """RequiredFieldsRemainingFieldId"":27420,",

   """EngageProgressFieldId"":27421,",

   """HistoryActionFieldId"":28523,",

   """HistoryFieldId"":28521,",

   """HistorySubmitByFieldId"":27489,",

   """HistorySubmitDateFieldId"":27490,",

   """RecordId"":",

   TRACKINGID(),

   "}")

   Important: Set ProductIdentifier to E4V or E4BU depending upon your license.

   Note: Unless you specifically configure the IdentifierFieldId in the custom object, the application/questionnaire key field is by default set as the identifier field. The Identifier field supports text, numeric, date, and tracking ID field types. Masks for text field are not supported.

   Note: If you publish a record to the Engage Portal before the Archer sync completes, all the calculated values in that published record are blank.

   The following table shows which Archer field name matches up to its related code in the calculated field.

   Field/Layout Name	Calculated Field String
   Name (First)	FirstNameFieldId
   Name (Last)	LastNameFieldId
   Email (Business)	EmailFieldId
   Job Title	JobTitleFieldId
   Contacts	ContactFieldId
   Engage Layout	LayoutId
   Additional Guidance	HelpTextFieldId
   Contact Email Address	ArcherContactEmailFieldId
   Contact Name	ArcherContactNameFieldId
   Due Date	DueDateFieldId
   Engage Status	StatusFieldId
   Publish Message	PublishMessageFieldId
   Requesting Company	RequestingCompanyNameFieldId Note: For E4BU RequestingCompanyNameFieldId is not required.
   Vendor Name	VendorNameFieldId Note: For E4BU VendorNameFieldId is not required.
   Identifier	ProductIdentifier
   Publish Language	PublishLanguageFieldId
   Portal Request URL	PortalRequestURLFieldId
   Continue sending default Engage notifications	IsEngageNotificationRequired
   Enable Comments	IsCommentsEnabled
   Visible Fields	VisibleFieldsFieldId
   Required Fields Remaining	RequiredFieldsRemainingFieldId
   Engage Progress	EngageProgressFieldId

2. Recalculate the application or questionnaire to populate the JSON for any existing content.

Task 3: Create a report

1. Open the Report Listing for your application or questionnaire, and click New.

2. In the Fields to Display section, select the tracking ID field and the calculated text field that you created in task 2.

3. In the Filters section, create filters as needed to limit what content is ready to be published.

   For example, you might create a new calculated field, "Required Engage Fields Populated", in your application or questionnaire 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 filter in your report so that only records where the value of "Required Engage Fields Populated" = Yes are returned in the search results (and thus are ready to be published).

4. Click Search.

   Save the search result as a global report.

Task 4: Obtain GUIDs

1. Obtain the GUID of the report you just created:

   1. In the report you just created, click Save > Save Report Changes.

   2. Note the contents of the ID field (without the curly braces).

2. Capture the GUIDs of the tracking ID and calculated text fields that you included in the report:

   1. From the menu, click  > Application Builder, and open your application or questionnaire.

   2. Click the Fields tab.

   3. Open both the tracking ID and calculated text field and note the contents of the ID fields (without the curly braces).

Task 5: Create the XML File

To manually configure the Source Definition in the data feed, you must create the following XML file.

1. Open a new file in text editor.

2. Add the following:

   <records>
   <record>
   <trackingId>1</trackingId>
   <jsonBody>test</jsonBody>
   </record>
   </records>

3. Save the file as an XML file.

Task 6: Create the data feed

1. From the menu, click > Integration > Data Feeds, and click Add New.

2. Give the data feed a unique name. If you plan to bulk publish from multiple applications or questionnaires, consider using the name of the application or questionnaire in the data feed name for easy reference.

3. In the Target field, select the application or questionnaire that you want to publish from.

4. Click the Source Connection tab, and in the Transport Method field, select JavaScript Transporter.

5. In the Transport Configuration section, upload the signed JavaScript file obtained from the Archer Community.

6. In the Custom Parameters section, create the following parameters.

   Key	Value Description
   baseUrl	The base URL of your Archer environment, not including the /default.aspx reference. For example: https://mysite.com/Archer Note: The sub-directory name is case sensitive.
   archerUser	An Archer user account that has, at minimum, read access to all of the content in the target application or questionnaire. This account is used to log in through the API and run the pre-configured report to retrieve the content staged for publish.
   archerPass	The password for the archerUser user account. Note: The password can't contain the <, >, or & characters.
   archerInstance	The instance name or pin. For example: 50000
   archerReportGUID	The report GUID that you captured in task 4.
   archerTrackingIDGUID	The tracking ID GUID that you captured in task 4.
   archerJsonFieldGUID	The calculated field GUID that you captured in task 4.
   archerSSOEnabled	This field can have a value of True or False. The longbowUrl value should be set according to the value set in this field.
   longbowUrl	When the archerSSOEnabled field value is False: The string appended to the baseURL parameter for each individual publish call, that was configured within IIS during the URL rewrite. For more information, see Publish URLs. For example: /engage/api/questionnaire/Publish. The string is present within the custom object in the application or questionnaire. Important: The URL must reflect the value you set while configuring the Server Farm. When the archerSSOEnabled field value is True: The longbowUrl value will be https://<engageagenthostname>:5001/api/v1/questionnaire/publish The job engine server should be able to communicate with the ArcherEngageAgent server and it's outbound port 5001 should be open.

   Note: Depending on your environment, you may also need to create the following parameters:

   Key	Value Description
   proxy	A proxy URL to route requests through. This parameter is required for SaaS/Hosted environments.
   verifyCerts	A boolean value to require SSL certificate verification (Defaults to True)
   batchSize	The upper limit for report results to retrieve (default = 10)

7. Click the Source Parsing tab, select XML as your Source Format.

   It is not required to use a transform with the default JavaScript, however you may add one if you want.

8. Click the Source Definition tab. Click the Source Data tab. Then click , and add the XML file created in task 5.

9. Click the Data Map tab.

10. Map the questionnaireID source field to the tracking ID field in your application or questionnaire.

11. Map the jsonBody source field to the calculated text field (JSON body created in task 2) in your application or questionnaire.

12. Click the Key Field Definitions sub-tab, click Add New Key, and select the tracking ID field that you mapped in step 10.

13. In the Target Record Processing section of the Run Configuration tab, select "Update existing record, if a matching record is found."

14. Click the Schedule tab and set how frequently you want the feed to run.

15. Click the General tab, change the status to Active, and save the feed.