Integrate with ServiceMax Zinc

Estimated Effort ~ 10 minutes or less

Learning Objectives

After completing this unit, you will be able to:

Getting Started with the Zinc Messaging API

Zinc connects technicians in real time with the people and information needed to confidently get the job done quickly and correctly, allowing the organization to reduce mean time to repair, boost customer satisfaction and improve employee engagement.

Using the Zinc Messaging API, in conjunction with TrueContext HTTP data destination, you can send messages to Zinc following the submission of a Form. Messages you compose in TrueContext can be delivered to a group, hotline, or directly to a user.

Step-by-Step

Your Use Case - Post a Message to Zinc 

Here is a common use case: A group of service managers would like to be notified in Zinc whenever a Work Order has been completed. The following video provides a quick overview of the workflow to give further context to the example which follows.

In Zinc

1. From the Zinc Admin Console, create an Official Group.

2. Next, create a bot or a hotline group in your Official Group.

Take note of the e-mail address associated with your Bot or Hotline. The characters preceding @bots.zincit.io or @hotlines.zincit.io make up your Bot Identification Token or Integration Token. You will need this token when configuring your Data Destination in TrueContext.

Screen_Shot_2019-09-10_at_10.08.02_AM.png

In TrueContext

1. Set up your HTTP Connection - Select the appropriate FormSpaceClosed FormSpaces are where forms are stored and organized in the TrueContext Web Portal. A TrueContext Team may have multiple FormSpaces, depending on their needs. Admins can set FormSpace permissions to control which users have access to the forms in that FormSpace., enter the Base URL (https://api.zincit.io), and select the box for Anonymous Access.

mceclip1.png

2. Compose your Document - Create a new Template-driven Text Document. The following example uses Handlebars to compile the message which we will send to Zinc.

The body of the JSON to be sent to Zinc contains three sentences. First, there is a hard-coded sentence indicating that a Work Order has been completed, along with a dynamic reference to Work Order Number.

            {{ answers.WorkOrderNumber.[0]}}

The second sentence includes a URL which is composed of a hard-coded reference to the ServiceMax Org where the completed work order can be viewed:

            https://na136.salesforce.com/{{answers.RecordID.[0]}}

Followed by a dynamic reference to the Record ID, which is the External ID for the Work Order in ServiceMax. 

https://na136.salesforce.com/{{answers.RecordID.[0]}}

Tip: In this example, the Work Order Number and Record ID have been dispatched to TrueContext using a User-Defined Custom Action in Service Max. To reference this data dynamically, we simply use the question unique ID for the questions in your form which will capture this data. The Work Order Number and Record ID could also be hard coded, instead. 

The entirety of the Handlebars template is provided here.

Info:We’re now TrueContext.
 {
  "body": "A Work Order has been completed: {{ answers.WorkOrderNumber.[0]}}. \n View Work Order in ServiceMax - https://na136.salesforce.com/{{answers.RecordID.[0]}}. \n View Service Report in TrueContext - https://live.prontoforms.com/data/{{dataRecord.identifier}}.pdf "
 }

3. Configure your Data Destination 
Configure an HTTP Data Destination. Under Connection Configuration, select the Connection established in Step 1 "Set up your Connection" above. For HTTP Method, select POST. In the URL Suffix, enter /hooks/v1/:id/message, where ":id" is replaced with your Bot Identification Token, or Integration Token as described above.

mceclip3.png

4. Submit your Form
Once you have submitted your form, check Zinc to see your new message!

Screen_Shot_2019-09-23_at_9.42.32_PM.png

Extend Your Use Case - Optionally Start a Conversation in Zinc 

Here is a common use case: While completing a form, a technician may seek help from a product or service specific Hotline as defined in Zinc. Using the Web Link help type on an Information Label question, we can launch a conversation directly from the form.

Zinc Hotlines are powered by Bots. So when someone sends a message to a hotline they are actually sending a message to a Hotline Bot. The Hotline Bot is a participant in the conversation and when it receives a message is creates a request.

Your Web URL should be configured as follows: 

            
                https://zinc-app.com/cnv?participants=ParticipantParameter

Where the participants parameter is the token of the Hotline Bot (which can be found in the Zinc Admin UI, as described above).

Note: Using the same configuration above, you could also launch a conversation with an Official Group by referencing a Bot token, or an individual participant. Learn more about Zinc Conversation Deep Links.

Simple Templates - Using DREL to compose basic messages

If you are composing a basic message which does not require Conditional Logic, then you may follow the simple examples below which make use of a DREL Document Template.

Example 1 Hardcode a message to be sent to an Official Group or Hotline in Zinc.  

{
  "body": "hello world."
}

Example 2 Using DREL, compose a message to an Official Group or Hotline in Zinc.

{
  "body": "%a[QuestionLabel]"
}

Example 3 Send a direct message to Zinc users. Identify recipients by email, as shown in the example below.  

{
  "recipients": ["address@example.com"],
  "body": "hello world."
}

Example 4 Optionally, use DRELClosed Data Reference Expression Language (DREL) is used to get form data and metadata and add it to a string, such as dates, usernames, or answers to questions in forms. to enter the recipient's email address.

{
  "recipients": ["%u[email]"],
  "body": "hello world."
}